search

bjmorgan / kinisi

A Python package for estimating diffusion properties from molecular dynamics simulations.
https://kinisi.readthedocs.io
MIT License
49 stars 11 forks source link

Add instruction for building the documentation #41

Closed dengzeyu closed 8 months ago

dengzeyu commented 8 months ago

Please add instructions showing how to build the documentation. It looks like the Makefile under the doc is not working properly. 

make html
Running Sphinx v7.2.6

Extension error:
Could not import extension sphinx_autodoc_typehints (exception: No module named 'sphinx_autodoc_typehints')
make: *** [Makefile:19: html] Error 2
dengzeyu commented 8 months ago

Just for tracking - this issue is related to the joss submission: https://github.com/openjournals/joss-reviews/issues/5984#issuecomment-1793653579

arm61 commented 8 months ago

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 (https://github.com/bjmorgan/kinisi/commit/28be82680216bdc6bcf24ca77a4f9d618393ae41 and https://github.com/bjmorgan/kinisi/commit/0ee39d47d616db3c73626ea6fe26e41ba5d8f9f7)

dengzeyu commented 8 months ago

@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 commented 8 months ago

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

arm61 commented 8 months ago

I have mentioned installing pandoc in this commit (https://github.com/bjmorgan/kinisi/commit/f123cc46a1c01198a17a557a095b121502f8516b)

bjmorgan commented 8 months ago

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

arm61 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

Yeah, that makes sense.

arm61 commented 8 months ago

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

bjmorgan commented 8 months ago

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

bjmorgan commented 8 months ago

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

arm61 commented 8 months ago

Done, see https://github.com/bjmorgan/kinisi/commit/fb70881e000706914873eed2463d349f870602d2

dengzeyu commented 8 months ago

@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 commented 8 months ago

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 commented 8 months ago

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 commented 8 months ago

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