Documentation website

[avdstaaij]

This in-progress PR will add proper documentation to GDPC!

The documentation is written with Sphinx. Sphinx supports many output formats, but my main focus is its HTML output (I'm using Sphinx-immaterial as the HTML theme).

Some screenshots

The documentation contains both fully hand-written parts and an API reference that gets automatically generated from the docstrings in the source code. A consequence of using Sphinx's API reference generation tooling is that docstrings need to be written in reStructuredText. This PR updates all docstrings to the new format. The hand-written parts are written in Markdown using Myst.

My plan is to host the documentation on readthedocs.io, which has many fantastic features that, compared to the current in-repository examples, make it much easier to point users to the correct version of the documentation. I'll set things up such that new version releases will automatically update the stable version of the docs, and pushes to master will update latest.

The documentation will replace the in-repository examples, so they'll be removed when this PR is done.

To preview the documentation, checkout the docs-sphinx branch, cd to docs, install the requirements in requirements.txt (optionally in a virtual environment), build and serve the documentation with make livehtml and visit http://127.0.0.1:8000 in a browser.

Because this PR touches almost every part of the code, and because it would be annoying if the docs became outdated before they're even published, all major changes to GDPC are on-hold until the docs are live.

[Flashing-Blinkenlights]

I haven't seen the rendered page, but it's already looking pretty solid!
My suggestion would be that we make sure the markdown files are at a good level, and then all other API documentation can come about as part of future patches (e.g. wherever a file is changed, docstrings should be made in the affected file), so that we can stay agile

[avdstaaij]

Thanks for the review, but do note this is still a draft. I haven't cleaned it up yet, and many parts are still under construction without necessarily being marked as such. I'll gladly hear your review once it's finished!

[avdstaaij]

My suggestion would be that we make sure the markdown files are at a good level, and then all other API documentation can come about as part of future patches (e.g. wherever a file is changed, docstrings should be made in the affected file), so that we can stay agile

My current plan is indeed to finish the remaining pages under Overview (performance, transformation, additional tools), make some other small changes, clean up the tutorial and to then publish. The API reference can be done gradually.

[avdstaaij]

@Flashing-Blinkenlights, actually, if you do feel like reviewing, the following pages are pretty much done:

• Introduction
• Getting started - Installation
• Tutorial - Building a house (I still plan to cut the bit about transformation, add screenshots for every step and fill in a few more things, but the already written text is review-ready).
• Overview - Basic world interaction
• Overview - Vectors (I might still move some of the vector_tools stuff to Overview - additional tools)
• Overview - The build area
• Overview - World slices and heightmaps (I do feel like this one is way too wordy, but that's not a high priority to fix right now)
• Overview - Building shapes
• Overview - Advanced blocks
• API Reference (The contents are autogenerated from docstrings, and don't need review right now. You could review the layout, but the possibilities there are fairly restricted).
• Changelog (Autogenerated from CHANGELOG.md, probably doesn't need review) (Before you mention it: I would prefer to only show the top-level sections in the table of contents on the right of the page, but that's currently not possible.)
• Overview - Python module structure (not sure whether this one is worth keeping)

There may be some broken links, which isn't much of a problem. I get notified of those by the build system, and I'll fix them all up before merging.

I would however appreciate it if you checked the code examples (do they run?). I did check them all myself, but I could always have made a mistake. In the long run we probably want to automte this somehow (maybe with this), but that's very low priority.

I won't be making any more changes to the overall structure in this PR, as it would be too much work at this point. It's more important to actually get the docs up.

I do strongly recommend looking at the actual website when reviewing, building it shouldn't be too hard with the instructions in the PR.

[avdstaaij]

I've filled in the missing bits in the tutorial and added images, so that part is fully done now!

[avdstaaij]

I've now also finished Overview - Improving Editor performance and simplified Overview - World slices and heightmaps a little.

[avdstaaij]

The documentation is now in a publishable state! I'm now going to look into putting it online with readthedocs. The docs will probably need to be on the master branch for that, so I'm going to merge this.