Setup of Sphinx for Docs

[artemp]

Its time for the Mapnik project to have awesome docs, easily maintainable and nicely presented.

We're limped along with docs on the Trac wiki for a while and we can now do better. We don't want to replace the trac wiki but we should expand on it systematically.

[http://sphinx.pocoo.org/ Sphinx] is an awesome documentation system for writing docs up, and I propose we use it to craft a new set of documentation for Mapnik2 and beyond.

[artemp]

[springmeyer] not going to get to this anytime soon. pushing to 0.7.0 milestone

[artemp]

[rweait] Well why don't I have a look at this?

Shall we put in svn (I'll need access) or shall I drop it elsewhere for you to pull?

[artemp]

[springmeyer] work started at: http://github.com/mapnik/sphinx-docs. marking against the sprint milestone so we can update the team and one in on next steps.

[artemp]

[dodobas] I've started to work on Sphinx docs, there is a 'preview' available at http://open.geof.hr/~dodobas/mapnik-docs/ which is updated from time to time.

I prefer to work on my own fork http://github.com/dodobas/sphinx-docs/, but I can push to main repository.

There are some issues:

• no clear documentation structure
• no idea how boost.python actually create bindings, source:trunk/bindings/python
• current docstrings are not ''compatible'' with sphinx, we could:
  • rewrite docstrings but I don't know how will Python built-in documentation deal with it
  • write separate documentation for each module/class in Sphinx, but it would need more work to keeping it in sync
• on which version should we base documentation, ''stable'' 0.7.x, or trunk
• a lot of documentation is missing :)

Any pointers would be helpful

[artemp]

[springmeyer] Replying to [comment:5 dodobas]:

I've started to work on Sphinx docs, there is a 'preview' available at http://open.geof.hr/~dodobas/mapnik-docs/ which is updated from time to time.

nice!

I prefer to work on my own fork http://github.com/dodobas/sphinx-docs/, but I can push to main repository.

okay.

There are some issues:

• no clear documentation structure

certainly. we as a community need to brainstorm about what is needed.

• no idea how boost.python actually create bindings, source:trunk/bindings/python

ya, boost is cool, but tricky. I need to work on boost bindings so that docstrings and argument hints are nicer. there may be no good solution but I've been meaning to look into it.

• current docstrings are not ''compatible'' with sphinx, we could:

right, can you describe the problems? Any idea how to get them compatible? is sphinx looking for a method that is missing?

based on http://bitbucket.org/birkenfeld/sphinx/issue/407/patch-do-not-inspect-boost-python-functions it appears we either need that patch or need to add func to boost python objects

or maybe we need to patch boost python?

* rewrite docstrings but I don't know how will Python built-in documentation deal with it

right, we want to match sure that our docstrings are ideally compatible with unittest too (which I know they are not right now but have not tried to look deeper).

* write separate documentation for each module/class in Sphinx, but it would need more work to keeping it in sync

We should have narrative docs in sphinx which are more important I think than autodoc which we can do separately with epydoc still if needed.

• on which version should we base documentation, ''stable'' 0.7.x, or trunk

My thinking has been only trunk - so we can launch the docs with Mapnik2, but I'm open to suggestions.

• a lot of documentation is missing :)

yes. we should scope it!

maybe we should have a skype documentation sprint sometime in october?

Any pointers would be helpful

the only other thing is that we're thinking about developing a JSON reference of all symbolizer properties and using that to auto-build reST pages at some point soon... see: #626 and http://github.com/mapnik/Cascadenik/tree/jsonreference

[artemp]

[mishok13] I have some experience with writing docs using sphinx, so some points:

• Regarding docstrings -- as far as it goes, docstrings are not the same as documentation and should be left as they are. Docstring should only answer the "what" question, while documentation should also explain "why" and "how". And yes, we'll have some lag before docs are updated after code updates, but I think that's perfectly fine for most people. But this puts more pressure on release manager to keep an eye on documentation being in sync with code prior to releases.
• The documentation structure is of secondary importance now, content should be our first priority. We should engage Richard in writing the tutorials and probably Jon, Tom and Artem to write about internals.
• Boost.Python is full of dark magic and I don't think we should be really explaining how it works. I haven't seen any projects which have (semi-)autogenerated Python bindings explain how SWIG, Cython or SIP work.

[artemp]

[dodobas] Replying to [comment:6 springmeyer]:

ya, boost is cool, but tricky. I need to work on boost bindings so that docstrings and argument hints are nicer. there may be no good solution but I've been meaning to look into it.

is source:trunk/bindings/python something generated automatically, or manually so i can fiddle with it directly?

We should have narrative docs in sphinx which are more important I think than autodoc which we can do separately with epydoc still if needed.

i've discovered this document,http://packages.python.org/an_example_pypi_project/sphinx.html#function-definitions, which explains these issues and demos different approaches using docstrings when integrating with sphinx.

my point of view is that docstrings should be changed just enough to render better with sphinx and not break doc, i.e. use blank lines and text formatting (emphasis, bullets, etc.), http://is.gd/fANqy, last line ..Equality of coords... is rendered poorly without blankline after colon.

Narrative docs are more important, but it would be nice to easily link them with library reference.

maybe we should have a skype documentation sprint sometime in october?

we can arrange it, on UTC time ofcourse :)

the only other thing is that we're thinking about developing a JSON reference of all symbolizer properties and using that to auto-build reST pages at some point soon... see: #626 and http://github.com/mapnik/Cascadenik/tree/jsonreference

this could be very helpful, do it once and auto-build it later

[springmeyer]

never got of the ground, now instead we have https://github.com/mapnik/mapnik-reference which is available through carto at https://www.mapbox.com/carto/