Page MenuHomePhabricator

Create a way to view docs-in-code from tools
Open, Needs TriagePublicFeature

Description

Hackathon project: a tool to collate and render tools' documentation from docs-in-code source (e.g. Markdown for Sphinx or mkDocs) — a 'Read the Docs' for Toolforge.

Background info: https://meta.wikimedia.org/wiki/Community_Tech/Documentation

Basic features:

  • Overview on the homepage of all available documentation, including all tools with user_docs_url defined (this latter part is somewhat done).
  • Cronjob to periodically look for tool repos with docs/ directories, to build their docs.
  • Support for multiple languages and versions, e.g. https://docs.toolforge.org/<tool>/<ver>/<lang>/ where ver can be a number, stable, or latest.
  • Support different docs generators. Sphinx and mkDocs are most likely.
  • Full-text search of the generated HTML. This could also extend to indexing the existing docs pages (~600 exist).
  • Possibly the design of the site can match what's developed for T273840 (or vice-versa).

More details t.b.a. — please add any ideas here!

Event Timeline

Samwilson changed the subtype of this task from "Task" to "Feature Request".

I've created a Phab project for the tool: tool-docs

I've created a Phab project for the tool: tool-docs

If you had done the project creation via https://toolsadmin.wikimedia.org/tools/id/docs your new project would have ended up nested under Tools. I think re-parenting once created still requires running magic scripts on the phabricator server itself.

Oh, I didn't know that! I've created T308087 to get it moved.

I think the basics of this tool are in place now. There are a bunch of bugs still of course and things to figure out; I've tried to record all that I can think of in other tickets:

So all that remains here is to remove the yellow banner.

Sound ok?