Page MenuHomePhabricator

Create documentation for addwiki library features
Closed, InvalidPublic


All libraries that need documentation can be found at .
Each of the libraries documentation is stored in the library repo within the docs directory.
The documentation is written using the RST markup.
An example commit introducing documentation for a single feature of one of the libraries can be found here but note that the example commit includes an error, and these services should not be constructed directly but instead retreived from the relevant factory.

Features that need documentation can be found in the lists below:

Once you've added documentation to a feature, make sure to click "Edit Task" on and change the checkbox from [] to [X] (to let others know that the feature has been documented).

Event Timeline

Would some pages on be a suitable place? e.g.

Normally, I'd say that e.g. Readthedocs or any system in which the documentation lives with the source code would be best, but that's not really the WikiWikiWay... ;-)

You could look into auto generated docs, it would make methods discoverable but it would be hard to connect the dots between the addwiki libs.

The best solution would be to actually write documentation(for example at, it's a pain but the result is the best.

I would say that you should go with creating generated docs, that would make it easier for other people such as myself to contribute to better docs based on the generated ones...

@Samwilson I did have a quick look at readthedocs as I do like libraries that use it as the docs are super easy to follow and navigate.

It looks like in that case each addwiki library would need a separate read the docs site? And the docs for each library would be contained within the git repo. Could work!

Maybe a docs repo could be created so a single readthedocs site could happen? Although then docs & code may get out of date.

Personally I think having the docs on is probably bad, and we would have the issue I mentioned above where docs get out of sync with the code etc.

General thoughts? I have an 5-8 hour train journey coming up (or something like that) and could probably write a decent set of docs in that time.

Yeah, readthedocs is great, it looks nice and keeps the documentation right in with the source code and so maintaining docs for different versions is completely simple. It requires people to learn reStructuredText, but that's not really very hard.

Interestingly, sphinx (which is what readthedocs is built on) is also used by phpDocumentor (they used to have a system of package-level docblocks, and 'tutorial' files, but that seems to have all gone away).

Oh, and there's also the possibility of using sphinx for documenting the addwiki libraries, but hosting the documentation on wmflabs. And if that's a possibility, so is using any of the static HTML site generators (preferably a PHP one, sculpin is popular) to do the same thing. :-)

If hosting it on labs, and building the doc-generation bit ourselves, it'd be easy to combine docs from different repos into a single final site.

So I had a quick chat with someone in the irc channel for readthedocs.

I am going to experiment with having an addwiki/readthedocs repo which hosts the main entry for the docs.
The docs for each library will then be in that given libraries repo.
Each library will be added as a sub project on readthedocs for the main site.
It might just all work out, have versioned docs for everything and be kind of nice!

That sounds like a terrific set up! So each package has a full /docs diretory with index.rst and etc.? Or would they be more skeleton RTD directories, and pulled together as one project when built? (I'm just wondering, because it's nice to be able to build docs locally while writing them.)

Addshore moved this task from Ready to In Progress on the Addwiki board.
Addshore added a project: User-Addshore.
Addshore moved this task from Unsorted 💣 to Back Burner 🏛️ on the User-Addshore board.

So I have claimed
The root is currently powered by and right now reflects what was on which I will get rid of a redirect to the docs.

The docs for each library can then live in the repe of each library individually and thus be maintained with the correct version in mind.
They can all also be sub projects and thus live under the same domain. etc.

I'll start creating the sub project docs now..!

And now all of the sub projects have been set up and the docs dir exist in the 4 repos / libraries to be documented.
Let the documentation commence!!!!!!

That's brilliant @Addshore! :-) I'll attempt to write some docs while I finish the cat-traversal thingo.

(And now everyone gets to learn a bit of rst as well!)

So I went ahead and migrated (and amended) the mediawiki-api-base docs and they can now be seen at :)

I will likely put lots of tasks up regarding the docs here in Google Code In this year!

Addshore renamed this task from Create 'actual' documentation to Create documentation for addwiki library features.Jan 3 2017, 11:12 PM
Addshore removed Addshore as the assignee of this task.
Addshore updated the task description. (Show Details)