doc requirements in [tool.poetry.dev-dependencies]?

[Jacob-Stevens-Haas]

Hey Andy, :wave:, I'm starting to work on the Kalman stuff and trying to make sure the docs build correctly. Apparently, poetry automatically installs the dev dependencies but not optional dependencies which must be specified individually. Can I copy all the documentation optional dependencies into the [tool.poetry.dev-dependencies] section of pyroject.toml?

Related: I can't build the docs even with the optional dependencies: mention this in #12.

Also, I have no idea why my /env/ folder isn't showing up since there's no .gitignore to ignore it, but maybe some poetry magic?

[andgoldschmidt]

Hi! Yes, I've specified everything for the docs under [tool.poetry.extras] so it can be installed via poetry install -E docs

[Edit: The reason for the above strategy is that the default [tool.poetry.dev-dependencies] is not supported by readthedocs (the listed packages won’t be used). Alternatively, readthedocs uses .readthedocs.yaml which allows us to include extra_requirements which can include groups specified via the -E flag.]

As to "Pandoc wasn't found" in #12 ... it seems like this should be a dependency, see https://nbsphinx.readthedocs.io/en/0.2.15/installation.html#pandoc

Did you test to see if installing pandoc in a clean poetry venv after installing derivative was enough to let you build the docs?

[andgoldschmidt]

I tested and was able to build the documentation within a fresh poetry venv without adding pandoc, so I'll go ahead and make the documentation edits necessary for merging #12 under the current install requirements.

[Jacob-Stevens-Haas]

Thanks for adding the docs dependencies :partying_face:

Did you test to see if installing pandoc in a clean poetry venv after installing derivative was enough to let you build the docs?

No, it still didn't build. After poetry install, poetry install -E, and installing pandoc via dpkg (and pip), I get the following errors:

DeadKernelError

``` (env) xenophon@pontus:~/github/derivative/docs$ make html Running Sphinx v4.5.0 WARNING: html_static_path entry '_static' does not exist building [mo]: targets for 0 po files that are out of date building [html]: targets for 159 source files that are out of date updating environment: [new config] 159 added, 0 changed, 0 removed /home/xenophon/github/derivative/docs/env/lib/python3.8/site-packages/matplotlib/animation.py:887: UserWarning: Animation was deleted without rendering anything. This is most likely not intended. To prevent deletion, assign the Animation to a variable, e.g. `anim`, that exists until you have outputted the Animation using `plt.show()` or `anim.save()`. warnings.warn( /home/xenophon/github/derivative/docs/env/lib/python3.8/site-packages/lockfile-0.12.2.dist-info/DESCRIPTION.rst:1: ERROR: Unknown target name: "fasteners". /home/xenophon/github/derivative/docs/env/lib/python3.8/site-packages/lockfile-0.12.2.dist-info/DESCRIPTION.rst:1: ERROR: Unknown target name: "oslo.concurrency". /home/xenophon/github/derivative/docs/env/lib/python3.8/site-packages/lockfile-0.12.2.dist-info/DESCRIPTION.rst:1: ERROR: Unknown target name: "openstack-dev". Notebook error: DeadKernelError in env/lib/python3.8/site-packages/nbclient/tests/files/Autokill.ipynb: Kernel died make: *** [Makefile:20: html] Error 2 ```

Also, whether running poetry install or poetry install -E docs I get the warning:

Warning: The lock file is not up to date with the latest changes in pyproject.toml. You may be getting outdated dependencies. Run update to update them.

This is my first time using poetry, so I'm not sure if I'm making a mistake.

[andgoldschmidt]

Ok, so installing pandoc via poetry is not enough, see: https://stackoverflow.com/a/71585691

The docs built fine on osx without pandoc, but not on linux. I've added pandoc to the poetry toml as part of the docs, but users must also get pandoc via apt-get because the python package only acts as a wrapper for this executable.

I also took care of that WARNING: html_static_path entry '_static' does not exist, we don't have any _static files to bother with.

---

Regarding the 2nd warning, make sure to interact with poetry packages in a poetry shell, and update / install: poetry shell poetry update poetry install -E docs

[Jacob-Stevens-Haas]

Hm, I made sure to get the pandoc binaries via dpkg on my system and then installed pandoc via poetry. I called make html in the poetry shell. I'm right now trying to try to see if they linked correctly