Page MenuHomePhabricator

Create documentation for addwiki library features
Open, Needs TriagePublic

Description

All libraries that need documentation can be found at https://github.com/addwiki .
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 https://phabricator.wikimedia.org/T145376 and change the checkbox from [] to [X] (to let others know that the feature has been documented).

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptSep 12 2016, 11:20 AM
Addshore added a project: Documentation.
Addshore moved this task from Incoming to Thinking on the Addwiki board.

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... ;-)

Abbe98 added a subscriber: Abbe98.Sep 13 2016, 8:39 AM

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.)

Addshore moved this task from Thinking to Ready on the Addwiki board.Sep 23 2016, 1:49 PM
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.
Addshore claimed this task.Sep 26 2016, 9:51 AM

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!

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 added a project: Google-Code-In-2016.
Addshore updated the task description. (Show Details)
Aklapper updated the task description. (Show Details)Jan 4 2017, 6:02 PM

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

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

Samwilson updated the task description. (Show Details)Oct 3 2017, 12:32 AM
jeropbrenda updated the task description. (Show Details)Mar 30 2019, 5:24 PM
jeropbrenda updated the task description. (Show Details)Apr 1 2019, 11:18 AM
jeropbrenda updated the task description. (Show Details)Apr 1 2019, 1:11 PM
jeropbrenda updated the task description. (Show Details)Apr 6 2019, 5:12 AM
jeropbrenda updated the task description. (Show Details)Apr 6 2019, 9:42 AM