Would some pages on mediawiki.org be a suitable place? e.g. https://mediawiki.org/wiki/Addwiki_PHP_library

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 mediawiki.org), 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 mediawiki.org 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 conf.py 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.)

So I have claimed https://addwiki.readthedocs.io
The root is currently powered by https://github.com/addwiki/readthedocs and right now reflects what was on https://addwiki.github.io 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. https://addwiki.readthedocs.io/projects/mediawiki-api-base 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 http://addwiki.readthedocs.io/projects/mediawiki-api-base :)

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

Imported three "test tasks" ("document two features in a repo"), one per repo:

• https://codein.withgoogle.com/tasks/5134353904435200/
• https://codein.withgoogle.com/tasks/4853575249297408/
• https://codein.withgoogle.com/tasks/6264159010291712/

Let's create more if things work well. Thanks :)