Contribute

In order to contribute to this wiki (for example adding tutorials, fixing typos etc.) you need to be a contributor of the GitHub repository.

The html files are updated whenever there is a push on the main branch: this triggers the automated sphinx workflow on GitHub that builds the static webpage.

Setup sphinx locally

Since the automated GitHub workflow takes some time to finish (a couple of minutes from the push) you may want to install sphinx on your local machine to test your updates before committing and pushing.

Attention

In order to have the same output on GitHub, make sure that all additional software needed for the build is also loaded by the workflow, i.e. make sure that every additional software you used is also listed in the docs/requirements.txt file.

I suggest creating a virtual enviroment with the installation of sphinx and all requirements after cloning the yambo-wiki repository:

$ python -m venv <somewhere>/sphinx-wiki
[...]
$ source <somewhere>/sphinx-wiki/bin/activate
(sphinx-wiki) $ pip install -r <somewhere-else>/yambo-wiki/docs/requirements.txt

Attention

Use the same version of python as in yambo-wiki/.github/workflows/sphinx.yml. Check also that the version of sphinx installed by pip is the same one used in the automated workflow.

To produce the html files, activate the sphinx-wiki environment and run the following command from inside the yambo-wiki folder:

$ source <somewhere>/sphinx-wiki/bin/activate
(sphinx-wiki) $ cd <somewhere-else>/yambo-wiki
(sphinx-wiki) $ ls
docs  README.md
(sphinx-wiki) $ sphinx-build -M html docs/source/ ~/Desktop/build

Attention

Redirect the output build folder (i.e. the one with html files) outside the yambo-wiki folder (for example to ~/Desktop).

Note

In alternative to -M also -b can be used. However when using -b all the output files are stored in build/, whereas with -M they are stored in build/html/. In case you want to change to -b update also publish_dir: <...> in .github/workflows/sphinx.yml. See also this page