NOTE: This is still WIP and would like to hear some feedback from other core devs along with some addon devs.
Addon docs are removed from source
One of the current issues is that the source files for add-ons and the documents are handled in two different locations. This makes the documentation hard to keep updated with the
The current wiki is broken and dead which has left the quality of addon documentation behind.
Proposal: Keep docs with code
A solution that has driven the success of documentation is keeping the documentation with the code. The solution has proved to work for Read the Docs and many other opensource projects.
See also: This idea of keeping docs and code together was illustrated by this presentation describing the philosophy behind RTD: https://www.youtube.com/watch?v=U6ueKExLzSY
Move to Sphinx
The current wiki documentation for add-ons is very sub-par with a lot of outdated/missing content. We want docs for our add-ons but make it very hard to edit the wiki.
So the proposal is similar to what we did with the manual. We will have one sphinx project where each addon has an index.rst the file where they can document their add-on how they please.
So the structure would look like this:
rBA - index.rst (overall index file) - conf.py - /add_curve_sapling - index.rst - other_rstfile.rst
Then the same can be done for contrib addons as well.
Require changes to docs with changes to addons
I think this is an idea that we want to aim for and can be much easier with having docs in the source.
Where would the docs live?
Add-ons contrib: docs.blender.org/addons_contrib/<blender_version>/<addon_name>
I want images in my docs
Images do not work well with GIT, however, I think a solution to this is using git-lfs.
I don't want to build every doc to just view edits to my addon
We can write a script similar to the one included with the manual: https://developer.blender.org/diffusion/BM/browse/trunk/blender_docs/manual/quicky_index_gen.py
Single file addons
We probably won't be able to support this we this structure so all add-ons will have to be in a directory. Unless we can extract documentation from these py-files.