Templates for documentation

C2SM / iconarray

R&D Python package for processing ICON data with xarray

https://c2sm.github.io/iconarray/

BSD 3-Clause "New" or "Revised" License

10 stars 2 forks source link

Templates for documentation #5

Closed cosunae closed 2 years ago

cosunae commented 2 years ago

Template for building a documentation with sphinx. Inspire in xarray.

Change the default (DARGLINT) convention to numpy style guide.
Use the sphinx_book_theme by the https://executablebooks.org/en/latest/ (same as xarray)

It can be built with

cd doc
make html

cosunae commented 2 years ago

No preferences on the style guide nor the theme. I just picked it from xarray, so please comment if you have a better choice

victoria-cherkas commented 2 years ago

(idp) bash-4.2$ make html
Running Sphinx v5.0.0
making output directory... done
WARNING: html_static_path entry '_static' does not exist

Theme error:
no theme named 'sphinx_book_theme' found (missing theme.conf?)

Am I missing something here? I am in doc branch and doc directory

victoria-cherkas commented 2 years ago

Ah I simply had to pip install sphinx_book_theme.

cosunae commented 2 years ago

should the sphinx_book_theme or any package required for building the doc part of the environment.yml ? Or you want to keep it dev env only (i.e. no doc) and add it requirements in the github action that builds the doc directly? @victoria-cherkas

victoria-cherkas commented 2 years ago

@cosunae we could have a environment-dev.yml with these additional packages, or just keep it in the github action. I dont really mind. Lets just keep it in the github action for now?

cosunae commented 2 years ago

sounds good to me then, we can keep it at the github action. Shall we merge or wait until #8 is ready?

victoria-cherkas commented 2 years ago

@cosunae I would like to wait until https://github.com/C2SM/iconarray/pull/8 is ready, which i hope is very soon... The problem I have is the environment - when I build the documentation locally in my conda env (build with the environment.yml) then it builds the documenation correctly, but outside of this conda environment (just pip installing sphinx and the theme etc) then it builds the documentation with the pages and all, but minus the content (the docstrings converted to documentation). And this is also what happens in the github action. Not sure which additional packages are required, or if I should just setup the github action to install the conda environment before make build.