Finalize docs

[DanielKotik]

I have added a section with build instructions for the documentation (for doing it locally), added a requirements.txt for docs dependencies and fixed remaining errors in conf.py. With these changes, we are ready to move on to setup the docs CI pipeline.

[timcallow]

Looks good.

I think the docstring in models.ISModel is not rendering correctly due to some incorrect formatting... But even if it were rendering there would the same error as we saw in PRs #18 and #16. I will fix later today.

[DanielKotik]

Looks good.

I think the docstring in models.ISModel is not rendering correctly due to some incorrect formatting... But even if it were rendering there would the same error as we saw in PRs #18 and #16. I will fix later today.

Mhh, for me this docsting looks good. Also, there are now warning messages anymore.

[timcallow]

Looks good.
I think the docstring in models.ISModel is not rendering correctly due to some incorrect formatting... But even if it were rendering there would the same error as we saw in PRs #18 and #16. I will fix later today.

Mhh, for me this docsting looks good. Also, there are now warning messages anymore.

Strange there are no warnings, but I don't see any of the class parameters displaying? And the propertys have no docs

[DanielKotik]

Looks good.
I think the docstring in models.ISModel is not rendering correctly due to some incorrect formatting... But even if it were rendering there would the same error as we saw in PRs #18 and #16. I will fix later today.

Mhh, for me this docsting looks good. Also, there are now warning messages anymore.

Strange there are no warnings, but I don't see any of the class parameters displaying? And the propertys have no docs

@timcallow Please follow these steps and report if the issues you mentioned persist:

cd docs
python3 -m venv docs-env
source docs-env/bin/activate
pip install -U pip
pip install -r requirements.txt
make clean
make apidocs
make html

This will create a simple virtual environment for the documentation using the dependencies given in requirements.txt I provided with branch finalize-docs. After testing, you can safely remove the virtual environment with rm -rf docs-env.

[timcallow]

@DanielKotik I did try these steps but the problem above persists.

To be clear make html does not raise any actual errors, but you can see from my screenshot that the ISModel Parameters are not shown (and the propertys also missing docstrings). Maybe it's not the case for you somehow?

[timcallow]

@DanielKotik I did try these steps but the problem above persists.

To be clear make html does not raise any actual errors, but you can see from my screenshot that the ISModel Parameters are not shown (and the propertys also missing docstrings). Maybe it's not the case for you somehow?

Anyway it's a simple fix, I'll do it later

[DanielKotik]

@DanielKotik I did try these steps but the problem above persists.
To be clear make html does not raise any actual errors, but you can see from my screenshot that the ISModel Parameters are not shown (and the propertys also missing docstrings). Maybe it's not the case for you somehow?

Anyway it's a simple fix, I'll do it later

Ahh, now I get it. The docstring of the __init__ method is not rendered at all. I was just wondering, that your properties are somehow grouped together. Anyway, we need to fix this. Also the parameter and attribute list seems not to correctly reflect the constructor signature (e.g. atom is missing).

[DanielKotik]

@timcallow Please have a look at https://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
It seems that constructor methods do not get parsed an rendered by Sphinx' autodoc by default. Let us first merge this PR, make a dedicated issue (I will do that -> #26 ) and fix it on a dedicated branch.

[timcallow]

@timcallow Please have a look at https://stackoverflow.com/questions/5599254/how-to-use-sphinxs-autodoc-to-document-a-classs-init-self-method
It seems that constructor methods do not get parsed an rendered by Sphinx' autodoc by default. Let us first merge this PR, make a dedicated issue (I will do that -> #26 ) and fix it on a dedicated branch.

Ok, I merge this PR now. See my comment on #26