search

RSE-Sheffield / software_engineering_best_practices

http://rse.shef.ac.uk/software_engineering_best_practices/
Other
4 stars 1 forks source link

Readthedocs #4

Open bobturneruk opened 3 years ago

bobturneruk commented 3 years ago

Should we signpost readthedocs?

DennisReddyhoff commented 3 years ago

It's in the appendix for the documentation section

bobturneruk commented 3 years ago

Pedantic, but it's sphinx that's there, not readthedocs. Perhaps this could be mentioned as part of https://github.com/RSE-Sheffield/software_engineering_best_practices/issues/9 i.e. "You might want to write docstrings so you can eventually do this..."?

DennisReddyhoff commented 3 years ago

Exercise Try changing the theme to one from https://www.sphinx-doc.org/en/master/usage/theming.html#builtin-themes Sphinx is by far the most commonly used documentation tool for Python projects. It's even used by the official Python documentation. If you have your Python project hosted at a publicly visible Git hosting site like GitHub, GitLab or Bitbucket, there is a free service called Read The Docs which can build and host your pages for you.

When using Git or any other version control software, you should make sure you check in your documentation sources alongside your code. For Sphinx, make sure you add conf.py, any rst files you create manually and the "make" files. Do not commit to Git any HTML output from running Sphinx.

It's at the bottom of the doc, but it is brief

bobturneruk commented 3 years ago

thanks - you're right