Writing documentation
We use the Sphinx tool to generate the GPAW documentation.
First, you should take a look at the documentation for Sphinx and reStructuredText. Also, read carefully the Writing documentation for ASE page.
Structure
When writing documentation easy accessibility and readability is key. To that end the documentation is split into several parts:
Documentation/Basic usage: This part contains basic usage instructions for GPAW, including references to parameters for the GPAW calculator object. This part should not contain extended examples, theory or code references.
Documentation/Advanced topics: This part contains explanations of the various features of GPAW. The focus here is on implementation specific information, not theory, as well as code references.
Documentation/Theory: This is the place for theoretical descriptions of methods used in the code. Reference to literature should be given.
Tutorials and Exercises: As the name suggests, this is the heading for any worked out examples, tutorials and exercises. Entries are further sorted into fields of physics or application.
One should always the different pages relating to one topic for easy navigation between theory, implementation and example sections.
Getting started
If you don’t already have your own copy of the GPAW package, then see Development workflow for how to set up your environment. Basically, you will need to do:
$ cd ~/gpaw
$ pip install -e .[docs]
This will give you an editable install of gpaw
(-e or --editable option to pip) and the [docs] part will
make pip install all the packages required to build the web-page
such as sphinx-rtd-theme and the
https://gitlab.com/gpaw/gpaw-web-page repository.
Then cd to the doc directory and build the html-pages:
$ cd ~/gpaw/doc
$ make
Make your changes to the .rst files, run the
make command again, check the results and if things
looks ok, make a branch, commit and push:
$ emacs index.rst
$ make
$ make browse
$ git switch -c my-changes-xyz
$ git add index.rst
$ git commit -m "..."
$ git push -u origin my-changes-xyz
Tip
You can also let gitlab-CI build the web-pages:
go to the pipeline of you merge request on gitlab.com
click the “docs” CI-job to start it
when the job has successfully finished, click “Browse” in the right sidebar under “Job artifacts”
Adding figures and tables
We don’t want to have png and csv files committed to Git. Instead, you should add the Python scripts that generate the figures and table data so that we can always generate them again if needed.
For quick scripts (no more than 5 seconds), see Running Python code to create figures. For more expensive scripts you can use AGTS for running long jobs that create figures or table data for this web-page. For an example, look at the source code here which will produce this: Tutorial: STM images - Al(111).
Spell check
To run a spell check install sphinxcontrib.spelling by running pip install sphinxcontrib-spelling,
navigate to gpaw/doc and run: make spelling.
If a correctly spelled word gets flagged, add it to gpaw/doc/words.txt.
Ascii-art math to LaTeX converter
Examples:
1+2
---
3
<a|b>
/ _ ~ ~ --- a
| dr 𝜓 𝜓 + > S
/ m n --- ij
aij