Deploy website

[niksirbi]

Configured sphinx with pydata_sphinx_theme and ability to render .md docs into .html. Currently working on auto-deploying the generated html build to a custom domain.

[niksirbi]

Sphinx configuration

• Sphinx project is in the docs directory, as it would be for a python package
• Website is built from docs/source.
• Sphinx configuration can be found in docs/source/conf.py. Important fields:
  • The theme is set to the pydata_sphinx_theme via html_theme = 'pydata_sphinx_theme'
  • Many useful extensions are enabled that will allow building API docs from docstrings, publishing with github pages, rendering markdown into html etc.
  • The html page title is set with html_title = 'Troubleshooting'
• index.rst is the homepage, which currently contains a TOC. This links to the actual content. which is currently stored as .md files in docs/source/pages. Headings up to the 3rd level appear in the TOC

GitHub workflows

A. Pull Request Docs Check

This action looks for Sphinx documentation folders in the project. It builds the documentation using Sphinx and any errors in the build process are bubbled up as GitHub status checks. The main purposes of this action are:

• Run a CI test to ensure documentation still builds.
• Allow contributors to get build errors on simple doc changes inline on GitHub without having to install Sphinx and build locally.

B. Build and Deploy Docs

This workflow is triggered from pushes on main (and temporarily on this branch, for testing).

• It pip installs the dependencies listed in docs/requirements.txt
• It bulds documentation into html using sphinx-build
• It deploys the html to a gh-pages branch using this GitHub action.
• The gh-pages branch gets automatically picked up by GitHub and published by default on neuroinformatics-unit.github.io/troubleshooting. GitHub pages needs to be enabled from GitHub repository settings.

How to build the website locally

git clone --branch deploy_website https://github.com/neuroinformatics-unit/troubleshooting.git troubleshooting
cd troubleshooting
pip install -r docs/requirements.txt
sphinx-build docs/source docs/build

The website can be viewed locally by opening docs/build/index.html

[niksirbi]

Latest major changes

• Markdown files are no longer in docs/source/pages, but directly in docs/source (simplifies URLs)
• Including html_baseurl = 'https://troubleshooting.neuroinformatics.dev/ in conf.py automatically creates the CNAME in build
• Copied all contents from old wiki, and decreased the TOC depth to 2
• Added a contributing guide to the repo README.md, which with some tricks, now also appears in index.rst (and thus, in the homepage)
• Added link to GitHub repo in the top-right space of the website

@lauraporta you may now proceed with the review