New manual and API reference

#1

After a lot of combined hard work, the move of the manual to the Sphinx documentation system is finally as good as complete. Check it out!
https://docs.panda3d.org/1.10/python/index

The new system makes the manual easier to navigate, integrates the API reference more tightly into the manual, allows us to export the manual to other formats (such as .pdf), allows us to host the documentation for multiple Panda versions side-by-side, and offers many other advantages that generally save time or improve the quality of the documentation. We’re most excited, however, about the fact that anyone can now contribute to the manual via GitHub pull requests, so that the documentation is now truly a collaborative effort.

There are still a couple of things that we want to take care of, such as creating a better landing page, adding a C++ API reference, and integrate any suggestions from the community before we fully replace the old manual and API reference.

Please let us know your opinions here, and file any issues you might encounter on the issue tracker:

Many thanks to brakhane, Moguri, tcdude, treamous, Kupoman and others for all their help in this effort!

7 Likes
#2

Based on a quick look, and on your description, it looks like quite an improvement, I think! :smiley:

Congratulations on bringing it to this milestone, and thank you for your work on it. :slight_smile:

#3

Great to see the documentation getting an overhaul :slight_smile: !

There are a couple of things I’m wondering about, though:

  • Wouldn’t this be a good time to start replacing the camelCase method names with the snake_case versions in both the manual and the API? If there is no (semi-)automatic way to do this, then I understand your reluctance, although I wouldn’t mind helping out with this (time permitting). The reason I’m mentioning this is that I’m worried about new members getting used to “bad habits” (I’m also thinking here about the built-in global variables) and then, in a couple of months/years/decades, being told that they will have to adapt their (by then potentially quite large) projects, due to these camelCase names becoming deprecated. This might not sit well with them, especially if they learn that the decision to do this was made even before they joined this community (I’m referring to this post in particular).
  • When I checked out the new API reference, I noticed that method and property names are no longer listed in alphabetical order, but rather in logical order, I guess. This might be preferable, although it might take some getting used to.

Regardless, I certainly do appreciate all the time and effort you’ve spent working on this!

#4

I wrote an implementation for automatic replacement, but I’m too lazy to bring the algorithm to the end, it’s in my head. Tricky handling of comments is required.