mirror of https://github.com/abinit/abinit.git
169 lines
5.3 KiB
Markdown
169 lines
5.3 KiB
Markdown
## 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:
|
|
|
|
```console
|
|
$ ./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: <span style="background-color: #E0E0E0;font-size:90%;"> [ [names|text] ] </span> will become <span style="background-color: #E0E0E0;font-size:90%;"> [ [text|namespace] ] </span>.
|
|
|
|
## 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:
|
|
|
|
```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
|