Manual -> RST

General Discussion
1

Hi all i am still fascinated with the idea of converting panda3d manual to RST format.

reStructuredText (RST) format is the default format for documenting python modules. I also happen to think is a pretty good WIKI like format that is both readable in text and renderd to HTML (or PDF) form. docutils.sourceforge.net/rst.html
This is a sample of how it looks on fairly big doc docs.python.org/_sources/referen … _stmts.txt

I have created a git repo to convert the manual to RST format. The git repo is setup to allow any one to commit so fleel free to help. Please follow the python style guide python.org/dev/peps/pep-0012/ .

github.com/treeform/panda3dmanual/tree/master

My goal is to convert the entire manual into RST format and throwing away some unneeded parts.
I feel that the manual has been turning into more of a “wiki” and some of the wiki parts can be wikified.
I also hope to produce a printable version of the manual.

I hope to model documentation after that for Django and Python project.
docs.djangoproject.com/en/dev/
docs.python.org/

Big hurdle is how to document c++ and python ways of doing things. I think i like the old way of using python for every thing and trusting C++ folks could figure it out for them selfs, only outlining major differences. But i am still out on this.

PS this has been discussed before:
discourse.panda3d.org/viewtopic … 0648#20648

2

This will be tricky for our manual, as we use a special kind of system and syntax for the Python<>C++ switching.

Still, even though rST might have some benefits, is there really a good reason to migrate the manual to it?

By the way, I did consider making the apiref tool write out rST before.

3

I wouldn’t be so quick to dismiss the C++ side of Panda. Just browsing over some of the recent topics in the C++ forum indicates that there remains a lot to be covered.

4

It’s true; and there has been increasing interest in C++ usage lately. I think welcoming C++ developers, rather than dismissing them as we have had a tendency to do in the past, will be beneficial to the Panda3D community as a whole.

Certainly Panda itself could benefit from the interest of more C+±capable developers, who are willing to contribute to the core engine. :slight_smile:

David

5

Great initiative!