1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
## 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.
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
|
