Documentation

Documentation

Possible options for the documentation

Github wiki

➕

• easy to edit (don't need to create PRs)
• In the same place as source code
• Markdown

➖

• just collaborators can contribute
• Cannot be generated easily

Github pages

https://pages.github.com/

➕

• Documentation can be stored in the same repository as source code
• docs of all projects are stored under same domain <orgname>.github.io/<projectname>
• Markdown
• (small plus) we can have <orgname>.github.io with general info about our team activities in upstream (links to all projects, talks, summer coding etc.)

➖

• We have to build and publish ourselves

readthedocs.io

➕

• Documentation can be generated and stored in the same repository as source code
• We can verify build in CI

➖

• All our projects have dedicated domains e.g conu.readthedocs.io
  • for packit, we can use packit.dev and redirect
• We have to use .rst, see the snippet from readthedocs web: Markdown doesn’t support a lot of the features of Sphinx, like inline markup and directives. However, it works for basic prose content. reStructuredText is the preferred format for technical documentation, please read this blog post for motivation
• currently, readthedocs.io doesn't allow installing packages using installer other than pip, which means if building fails because of any package we cannot do much with it. It happend in conu with enum34 package.