What about distributing html builds along with the distributions?

[ubaldot]

I often travel and I don't have internet, and I typically use such time to play with animations. I would like to access the html docs locally.
A trivial solution would be to clone the repo and build the docs on my machine.
I actually did it for a while, but it always a hassle due to that the released version (installed by conda) may mismatch with the main branch (the latest: I have the 0.17.3 version installed and I got the No module named 'manim.utils.docbuild.autocolor_directive' which exist in the main branch but not in the latest release).

I was wondering if it is possible to distribute the html builds along with the distribution and eventually add a command like manim docs that simply open the index.html file from site-package.

What do you think?

[behackl]

$ du -hs docs/build/html/
100M    docs/build/html/

Not a good idea, sorry. The documentation is too large to be packaged with the code.

The version mismatch should not happen though, a system installation of manim should not interfere with building the docs for the latest main branch. Do you work in a separate virtual environment when building the documentation? I'd recommend doing that.

[ubaldot]

Ah too bad that the docs is so large. Then I will do something else when I will be traveling :D

I understand that there should not be interference between the installed version and the building of the docs, but it seems that there are mismatches (see my post above for example).
Yes, I do use a virtual environment where I have pretty much installed only manim from conda plus other sphinx stuff for building the docs.

[behackl]

Yes, I do use a virtual environment where I have pretty much installed only manim from conda plus other sphinx stuff for building the docs.

But that would be the problem: if manim is installed via conda in the same venv that you use to build the documentation of the development version, it will use the already installed version of manim to render -- which then fails with the message you posted above.

When trying to build the documentation, the version of manim that is installed needs to match the version of the documentation you are trying to build, otherwise you might run (as you actually do) into compatibility issues.

[ubaldot]

Ah right, correct!
Please correct me if I am wrong, but then I see two solutions here, each with its pros and cons:

1. Install a released version and use online docs. In this way you can use conda, pip or whatever tool you use but then the docs is only available online.
2. Use the main branch. In this case you can build the docs but you cannot install manim through e.g. conda (unless you create a conda package yourself) but you should use poetry - at least it is suggested to.

I was thinking: what if we add only the docs source code in the release and add all the sphinx stuff for building it as dependency?
In this way a user could build an offline docs directly from the release and the distribution package would not be too large. Certainly, there would be more dependencies to install, but sphinx is not an exotic framework and it quite common.

As a user, the idea of having a software installed whose documentation is only available online is a bit strange, but perhaps it is just me. :)

[naveen521kk]

Maybe we can enable https://docs.readthedocs.io/en/stable/downloadable-documentation.html (I'm thinking for the Zipped HTML format)? In that case, one can download docs from website directly. @ubaldot will that work for you?

[ubaldot]

@naveen521kk This could be a nice solution indeed!

[ubaldot]

Awesome! But I don’t understand now how shall I download the file :/