On 19 May 2014 22:59, Pyfisch pyfisch@googlemail.com wrote:
Sphinx can generate really good docs from the source code and you only need to change source code, and then we could generate and host the docs on the labs server. If we require to update mediawiki.org, we wont ever reach sync between code and documentation. I propose to remove the documentation on mediawiki and only use sphinx for docs, but everywhere.
Recently, I've been thinking a lot about this, so this was a good reason to write those thoughts down; I created a wiki page for that:
https://www.mediawiki.org/wiki/Help:Pywikibot/Documentation_RFC
Basically, I'm not a big fan of sphinx because of the lack of accessibility (and I *loathe* restructuredtext), and we lose e.g. translations when we switch, so I would prefer something centered around mw.org. However, I *do* agree it's a huge issue that code and docs are never in sync. Anyway, see the not-yet-a-real-RFC for my thoughts.
Merlijn
On Tuesday, May 20, 2014, Merlijn van Deen valhallasw@arctus.nl wrote:
Recently, I've been thinking a lot about this, so this was a good reason to write those thoughts down; I created a wiki page for that:
https://www.mediawiki.org/wiki/Help:Pywikibot/Documentation_RFC
Basically, I'm not a big fan of sphinx because of the lack of accessibility (and I *loathe* restructuredtext), and we lose e.g. translations when we switch, so I would prefer something centered around mw.org. However, I *do* agree it's a huge issue that code and docs are never in sync. Anyway, see the not-yet-a-real-RFC for my thoughts.
Related? https://www.mediawiki.org/wiki/Data_%26_Developer_Hub
The Engineering Community team and others at the WMF are planning to work in this project to sort out and showcase the MediaWiki API + neighbors. Your feedback is welcome there.
Hi Merlijn,
Merlijn van Deen schreef op 20-5-2014 22:14:
On 19 May 2014 22:59, Pyfisch <pyfisch@googlemail.com mailto:pyfisch@googlemail.com> wrote:
Sphinx can generate really good docs from the source code and you only need to change source code, and then we could generate and host the docs on the labs server. If we require to update mediawiki.org <http://mediawiki.org>, we wont ever reach sync between code and documentation. I propose to remove the documentation on mediawiki and only use sphinx for docs, but everywhere.Recently, I've been thinking a lot about this, so this was a good reason to write those thoughts down; I created a wiki page for that:
https://www.mediawiki.org/wiki/Help:Pywikibot/Documentation_RFC
Good overview! Maybe something to take into account: We have different groups of users for the documentation: 1. People who just want to install pywiki and run scripts 2. People who want to mess with the code
Maybe you want the first part to be more based onwiki and the second part more in code. If we start talking about structure: Why do we have different namespaces and subpages on MediaWiki.org? Makes it quite hard to find stuff.
Maarten
My idea about documentation is something mediawiki's API, we have a documentation in in codes as docstring but for further information we refer people to a page in mediwki.org something like this: http://en.wikipedia.org/w/api.php
** list=geosearch (gs) ** Returns pages around the given point https://www.mediawiki.org/wiki/Extension:GeoData#list.3Dgeosearch
This module requires read rights Parameters: gscoord - Coordinate around which to search: two floating-point values separated by pipe (|) gspage - Title of page around which to search gsradius - Search radius in meters This parameter is required
and etc.
The benefit of this act is we can have two kinds of documentation, one for bot ops (in codes) and one for developers and code writers (in mediawiki.org)
adding these links to docstrings is pretty much easy thing to do
Best
On Wed, May 21, 2014 at 11:42 PM, Maarten Dammers maarten@mdammers.nlwrote:
Hi Merlijn,
Merlijn van Deen schreef op 20-5-2014 22:14:
On 19 May 2014 22:59, Pyfisch pyfisch@googlemail.com wrote:
Sphinx can generate really good docs from the source code and you only need to change source code, and then we could generate and host the docs on the labs server. If we require to update mediawiki.org, we wont ever reach sync between code and documentation. I propose to remove the documentation on mediawiki and only use sphinx for docs, but everywhere.
Recently, I've been thinking a lot about this, so this was a good reason to write those thoughts down; I created a wiki page for that:
https://www.mediawiki.org/wiki/Help:Pywikibot/Documentation_RFC
Good overview! Maybe something to take into account: We have different groups of users for the documentation:
- People who just want to install pywiki and run scripts
- People who want to mess with the code
Maybe you want the first part to be more based onwiki and the second part more in code. If we start talking about structure: Why do we have different namespaces and subpages on MediaWiki.org? Makes it quite hard to find stuff.
Maarten
Pywikipedia-l mailing list Pywikipedia-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/pywikipedia-l
pywikipedia-l@lists.wikimedia.org