abinit/doc

Getting started with mkdocs

!!! warning

The code supports py2.7 and python3.6 but py3k is **strongly** suggested
especially when building the final version before deploying
as py3k has native support for unicode.

In addition, all the commands should be run in the top abinit directory (so one level above /doc)

Install the python packages required to build the static website with:

pip install -r requirements.txt

then install the mkdocs plugin with:

cd abimkdocs_plugin
python setup.py install

If you use conda, you may want to create a new environment based on python3.6 with:

conda create -n abinit-abimkdocs-2 python=3.6
source activate abinit-abimkdocs

and then install the packages with pip (see above commands).

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. Make sure you are in ~abinit, and then start our customized server by running the mksite.py serve command with the --dirtyreload option:

$ ./mksite.py serve --dirtyreload
Regenerating database...
Saving database to /Users/gmatteo/git_repos/abidocs/doc/tests/test_suite.cpkl
Initial website generation completed in 9.17 [s]
Generating markdown files with input variables of code: `abinit`...
...
...
INFO    -  Building documentation...
INFO    -  Cleaning site directory
[I 170826 03:37:05 server:283] Serving on http://127.0.0.1:8000
[I 170826 03:37:05 handlers:60] Start watching changes
[I 170826 03:37:05 handlers:62] Start detecting changes

Open up http://127.0.0.1:8000/ in your browser, and you'll see the default home page being displayed.

Use:

$ ./mksite.py --help

to get the list of commands and:

$ ./mksite.py COMMAND --help

to get the documentation of COMMAND.

Notes

topics are still in Yaml format wikilink syntax: [ [names|text] ] will become [ [text|namespace] ] .

Troubleshooting

If you get error message about ASCII being used as default encoding on your machine add:

export LC_ALL=en_US.UTF-8
export LANG=en_US.UTF-8

to your ~/.bashrc and source it

How to add new variables

The yaml database has been replaced by python modules. The variables are now declared in ~abinit/abimkdocs/variables_CODENAME.py.

This file consists of a list of dictionaries, each dictionary contains the declaration of a single variable and the associated documentation in markdown format. Wikilinks, latex and markdown extensions can be used inside text. This is, for example, the declaration of the accuracy variable in python:

Variable(
    abivarname="accuracy",
    varset="basic",
    vartype="integer",
    topics=['Planewaves_basic', 'SCFControl_basic'],
    dimensions="scalar",
    defaultval=0,
    mnemonics="ACCURACY",
    text="""
Allows to tune the accuracy of a calculation by setting automatically the
variables according to the following table:

accuracy         | 1         | 2          | 3            | 4            | 5         | 6
---              |---        |---         |---           |---           |---        |---
[[ecut]]         | E_min     | E_med      | E_med        | E_max        | E_max     | E_max
[[pawecutdg]]    | ecut      | ecut       | 1.2 * ecut   | 1.5 * ecut   | 2 * ecut  | 2 * ecut
[[fband]]        | 0.5       | 0.5        | 0.5          | 0.5          | 0.75      | 0.75
...

For a parallel calculation, [[timopt]] is enforced to be 0.
...
""",
),

Adding a new variable is easy. Edit the python module and add a new item at the end of the list. A template is provided ...

How to add a new bibtex entry

Citations must be in bibtex format and provide enough information so that the python code can generate appropriated links in the website. For published work with a DOI, we strongly recommend avoiding a cut&paste from your bibtex files (there are units tests to enforce the presence of particular entries in the bibtex document and your bibtex may not fullfill these requirements).

A much better solution is to use BetterBib and the DOI of the article to fetch data from Crossref and produce the bibtex entry. BetterBib is available from the Python Package Index, so simply type:

pip install betterbib

and then use doi2bibtex from the command line:

doi2bibtex 10.1103/PhysRevLett.96.066402

Add the entry to the bibtex file and use the FirstAuthorYear convention for the key (make sure it's not a duplicated entry). Note that the bibtex ID must be of the form "FirstauthornameYEAR", e.g. "Amadon2008" (start with an uppercase letter, then lower case, then four-digit year). Possibly, a letter might be added in case of ambiguity: e.g. there exists also Amadon2008a Then, build the HTML pages using mksite.py serve.

Run the tests in ./tests/test_bibtex.py with pytest (see next section) to validate your changes.

Running the unit tests

Unit tests are located in the ./tests directory. To execute the tests, install pytest with:

pip install pytest

and then:

pytest -v ./tests/

Use

pytest -v ./tests/test_variables.py

to execute a particular module.

Checking links with linkchecker

Build the website with:

./mksite.py build

then use

linkchecker site/index.html > links.err

!!! important

For the time being, linkchecker python2.7