Add instruction for building the documentation about kinisi

[dengzeyu]

Just for tracking - this issue is related to the joss submission: openjournals/joss-reviews#5984 (comment)

[arm61]

Ah this is because there is a separate set of dependencies in the pyproject.toml for the docs. I have add the following commits that explain this in the documentation (28be826 and 0ee39d4)

[dengzeyu]

@arm61 I just tried to build the documentation, but I got following error. Could you please help me fix it?

pip install -e '.[docs]'
make html

Notebook error:
PandocMissing in arrhenius_t.ipynb:
Pandoc wasn't found.
Please check that pandoc is installed:
https://pandoc.org/installing.html
make: *** [Makefile:19: html] Error 2

I confirm I've installed the pandoc

Package                       Version      Editable project location
----------------------------- ------------ -----------------------------
accessible-pygments           0.0.4
alabaster                     0.7.13
ase                           3.22.1
asttokens                     2.4.1
attrs                         23.1.0
Babel                         2.13.1
beautifulsoup4                4.12.2
biopython                     1.81
bleach                        6.1.0
certifi                       2022.12.7
charset-normalizer            3.3.2
codeclimate-test-reporter     0.2.3
comm                          0.1.4
contourpy                     1.2.0
corner                        2.2.2
coverage                      7.3.2
cycler                        0.12.1
debugpy                       1.8.0
decorator                     5.1.1
defusedxml                    0.7.1
docutils                      0.20.1
dynesty                       2.1.3
emcee                         3.1.4
exceptiongroup                1.1.3
executing                     2.0.1
fasteners                     0.19
fastjsonschema                2.18.1
fonttools                     4.44.0
future                        0.18.3
GridDataFormats               1.0.2
h5py                          3.10.0
idna                          3.4
imagesize                     1.4.1
importlib-metadata            6.8.0
importlib-resources           6.1.0
iniconfig                     2.0.0
ipykernel                     6.26.0
ipython                       8.17.2
jedi                          0.19.1
Jinja2                        3.1.2
joblib                        1.3.2
jsonschema                    4.19.2
jsonschema-specifications     2023.7.1
jupyter_client                8.5.0
jupyter_core                  5.5.0
jupyterlab-pygments           0.2.2
kinisi                        0.7.2        /home/jerry/app/source/kinisi
kiwisolver                    1.4.5
latexcodec                    2.0.1
markdown-it-py                3.0.0
MarkupSafe                    2.1.3
matplotlib                    3.8.1
matplotlib-inline             0.1.6
MDAnalysis                    2.6.1
mdit-py-plugins               0.4.0
mdurl                         0.1.2
mistune                       3.0.2
mmtf-python                   1.1.3
monty                         2023.11.3
mpmath                        1.3.0
mrcfile                       1.4.3
msgpack                       1.0.7
myst-parser                   2.0.0
nbclient                      0.8.0
nbconvert                     7.10.0
nbformat                      5.9.2
nbsphinx                      0.9.3
nest-asyncio                  1.5.8
networkx                      3.2.1
numpy                         1.26.1
packaging                     23.2
palettable                    3.3.3
pandas                        2.1.2
pandoc                        2.3
pandocfilters                 1.5.0
parso                         0.8.3
pexpect                       4.8.0
Pillow                        10.1.0
pip                           23.0.1
platformdirs                  3.11.0
plotly                        5.18.0
pluggy                        1.3.0
plumbum                       1.8.2
ply                           3.11
prompt-toolkit                3.0.39
psutil                        5.9.6
ptyprocess                    0.7.0
pure-eval                     0.2.2
pybtex                        0.24.0
pydata-sphinx-theme           0.14.3
Pygments                      2.16.1
pymatgen                      2023.10.11
pymatgen-analysis-diffusion   2023.8.15
pyparsing                     3.1.1
pytest                        7.4.3
pytest-cov                    4.1.0
python-dateutil               2.8.2
pytz                          2023.3.post1
PyYAML                        6.0.1
pyzmq                         25.1.1
referencing                   0.30.2
requests                      2.31.0
rpds-py                       0.12.0
ruamel.yaml                   0.18.5
ruamel.yaml.clib              0.2.8
scikit-learn                  1.3.2
scipy                         1.11.3
setuptools                    65.6.3
six                           1.16.0
snowballstemmer               2.2.0
soupsieve                     2.5
spglib                        2.1.0
Sphinx                        7.2.6
sphinx-autodoc-typehints      1.24.1
sphinxcontrib-applehelp       1.0.7
sphinxcontrib-devhelp         1.0.5
sphinxcontrib-htmlhelp        2.0.4
sphinxcontrib-jsmath          1.0.1
sphinxcontrib-qthelp          1.0.6
sphinxcontrib-serializinghtml 1.1.9
stack-data                    0.6.3
sympy                         1.12
tabulate                      0.9.0
tenacity                      8.2.3
threadpoolctl                 3.2.0
tinycss2                      1.2.1
tomli                         2.0.1
tornado                       6.3.3
tqdm                          4.66.1
traitlets                     5.13.0
typing_extensions             4.8.0
tzdata                        2023.3
uncertainties                 3.1.7
uravu                         1.3.0
urllib3                       2.0.7
wcwidth                       0.2.9
webencodings                  0.5.1
wheel                         0.38.4
yapf                          0.40.2
zipp                          3.17.0

[arm61]

I am able to build successfully with pandoc 3.1.3 perhaps updating will help?

[arm61]

I have mentioned installing pandoc in this commit (f123cc4)

[bjmorgan]

Can we not specify pandoc (with a suitable minimum version) in the usual way as a requirement?

[arm61]

Pandoc isn't a Python package (there is a python interface but you still need to conda/mamba/brew install pandoc to get it to work).

[bjmorgan]

Is that why it shows up in `pip`? Also, this means the `pip list` output doesn’t actually tell us if `pandoc` is correctly installed.

[arm61]

Yeah, that makes sense.

[arm61]

Also why my version is so much higher than @dengzeyu's (it is actually a different thing)...

[bjmorgan]

@dengzeyu: what do you get from pandoc -v from the command line?

[bjmorgan]

@arm61 suggestion that you link to the "installing pandoc" page (https://pandoc.org/installing.html) from installation.md.

[arm61]

Done, see fb70881

[dengzeyu]

@dengzeyu: what do you get from pandoc -v from the command line?

I got following

pandoc -v
pandoc 2.12
Compiled with pandoc-types 1.22, texmath 0.12.1.1, skylighting 0.10.4,
citeproc 0.3.0.8, ipynb 0.1.0.1
User data directory: /home/jerry/.local/share/pandoc
Copyright (C) 2006-2021 John MacFarlane. Web:  https://pandoc.org
This is free software; see the source for copying conditions. There is no
warranty, not even for merchantability or fitness for a particular purpose.

Actually, I tried to install using conda but I can only find the version 2.12, maybe some channels should be added?

conda search pandoc
Loading channels: done
# Name                       Version           Build  Channel
pandoc                      1.19.2.1      hea2e7c5_1  pkgs/main
pandoc                         2.2.1      h629c226_0  pkgs/main
pandoc                       2.2.3.2               0  pkgs/main
pandoc                       2.9.2.1               0  pkgs/main
pandoc                          2.10               0  pkgs/main
pandoc                        2.10.1               0  pkgs/main
pandoc                          2.11      hb0f4dca_0  pkgs/main
pandoc                          2.12      h06a4308_0  pkgs/main
pandoc                          2.12      h06a4308_1  pkgs/main
pandoc                          2.12      h06a4308_3  pkgs/main

I think the pandoc in conda/pip is too old... Yeah adding a sentence in the installation page and asking for install the new version should be fine.

kinisi/lib/python3.9/site-packages/nbsphinx/__init__.py:1058: RuntimeWarning: You are using an unsupported version of pandoc (2.12).
Your version must be at least (2.14.2) but less than (4.0.0).
Refer to https://pandoc.org/installing.html.

[bjmorgan]

Actually, I tried to install using conda but I can only find the version 2.12, maybe some channels should be added?

It is unclear whether that refers to the pandoc Python interface, or pandoc itself. I usually install pandoc using the recommended package manager as per the installation instructions (conda is not mentioned on that page).

[dengzeyu]

Actually, I tried to install using conda but I can only find the version 2.12, maybe some channels should be added?

It is unclear whether that refers to the pandoc Python interface, or pandoc itself. I usually install pandoc using the recommended package manager as per the installation instructions (conda is not mentioned on that page).

Yes. I just installed the pandoc using the system package manager and now it's working.

[arm61]

Running mamba install pandoc got me the 3.1.3 version. I have added the link to the installation instructions.