it would be nice to start using readthedocs more seriously for Slicer core module documentation. People could just use their GitHub account to contribute (no more wiki signup troubles), we could keep the code and documentation tightly linked, etc.
Blender manual on ReadTheDocs is a good example of how it could look. It is a huge manual, so most probably we can use the same techniques, we would not need to invent anything new. Its source code is available here: https://developer.blender.org/diffusion/BM/
The main complication right now is that the documentation is generated from a separate branch. Keeping the documentation branch in sync with master is difficult because for example I want to merge changes of util.py from master, but some files are only present in the documentation branch.
Should we maintain code and documentation in same repository and branch?
Advantages of keeping code and documentation together:
- Documentation and code would be tightly synchronized. We could ensure that even small details, programming examples, etc. are always accurate.
- We could do code and documentation updates in the same pull request (we can better enforce consistency and quality, include documentation testing in continuous integration, etc).
- Documentation and code is kept together in smaller projects anyway, such as in Slicer extensions. We would use the same operating mechanism for Slicer core and extension documentation.
- We can generate user and API documentation from the same repository. User and developer documentation are often interlinked, so it is useful if we can generate them together.
Advantages of keeping documentation in separate repositories:
- Smaller code repository size. Slicer source code size is currently about 110MB. Over time, documentation would probably make it about 50% larger (estimated based on Blender manual, which is 70MB: contains 1900 png files, 1200 rst files).
- Access control and development process could be defined separately for source code and documentation.
I lean towards keeping code and documentation in one repository and branch. What do you think?
@jcfr @pieper @cpinter @ihnorton @fedorov