Add basic docs with sphinx

[niksirbi]

This will tackle issues #25 and #43

[samcunliffe]

That was quick!

[niksirbi]

That was quick!

Well, the build is currently failing. So still, some debugging to do.

[codecov-commenter]

Codecov Report

Merging #45 (35abb84) into main (3e52266) will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##            main     #45   +/-   ##
=====================================
  Coverage   9.38%   9.38%           
=====================================
  Files          4       4           
  Lines        373     373           
=====================================
  Hits          35      35           
  Misses       338     338           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

[niksirbi]

Summary of changes

• Added necessary Sphinx files in docs folder. The important ones are listed below:
  • docs/requirements.txt: documentation build requirements
  • docs/source/conf.py: configures the sphinx build (including theme, extensions, URL, etc.)
  • docs/source/index.rst: this corresponds to the docs homepage, and must contain a table-of-contents with refs to other files in the docs/source directory. Additional docs paged can be added as separate .md or rst files.
• Added a github workflow .github/workflows/publish_docs that is triggered by pushes to main. This does the following:
  • installs Sphinx and the other docs build requirements specified in docs/requirements.txt
  • build the contents of docs/source into HTML and transfers the build to a gh-pages branch.
  • The rendered build is available at: https://sainsburywellcomecentre.github.io/WAZP/ (the reason you can already see it up, is because I temporarily enabled the above workflow for this branch as well, will disable before merge)
• Transferred most of the previous contents of the README.md to a CONTRIBUTING.md and significantly expanded the "how to contribute" information.
• Expanded the README.md file by adding badges, and instructions for installing and launching WAZP.
• I made the contents of the README.md appear on the homepage of the docs website, while the CONTRIBUTING.md file is rendered as a separate page on the same website. I accomplished this via linking to the corresponding repo files from inside docs/source (to avoid content duplication).

Remaining issues

• Originally, I wanted to add an additional workflow that would be triggered upon pull requests and would check whether the PR breaks the docs Sphinx build. However, that particular workflow gave me many problems (because the action I was relying on no longer seems to be actively maintained, see this issue) and I have abandoned it for now. For the future, we will still need an action that checks the docs build upon PRs (any ideas @samcunliffe ?)
• Currently I have not included any API docs (I don't we need that for now, since the users be interacting with the dashboard, not directly calling Python functions). That said, it will be easy to auto-generate API docs with Sphinx, should we need them in the future.
• Actual instructions on how to use the dashboard are currently missing, but I figured that these should come in separate PRs. These could take the form of adding more.md files to docs/source, and including them in the table-of-contents in docs/source/index.rst

[samcunliffe]

The rendered build is available at: https://sainsburywellcomecentre.github.io/WAZP/

😻 It looks really nice 👍 👍

[samcunliffe]

This looks really good 😻!!!

I've left some pedantic comments for our new user-facing README.

I didn't comb through CONTRIBUTING quite so thoroughly because I expect it will evolve a fair bit and this is already an excellent base from which to build.

Currently I have not included any API docs (I don't we need that for now, since the users be interacting with the dashboard, not directly calling Python functions). That said, it will be easy to auto-generate API docs with Sphinx, should we need them in the future.

I'd put them in right now if it's easy. Can you simply autodoc the lot? If it's a pain then merge this PR first.

Actual instructions on how to use the dashboard are currently missing, but I figured that these should come in separate PRs. These could take the form of adding more.md files to docs/source, and including them in the table-of-contents in docs/source/index.rst

Agreed.

[samcunliffe]

This will tackle issues #25 and #43

This is potentially a pro-tip 😎 or potentially patronising if you already know 😬 ...

When you mention GH issues on GH PRs and/or comments, you can use some magic words and the issue gets linked/closed.

I think we don't close #43 yet.

[niksirbi]

When you mention GH issues on GH PRs and/or comments, you can use some magic words and the issue gets linked/closed.

I actually knew this, but deliberately didn't use one of the magic words (since when I opened the PR I wasn't sure which issues would be closed by it 😈 ).

Now however I can say with confidence that this PR closes #25 😉