How to build the documentation?


I would like to build the documentation in EPUB format so that I can read it on my e-book reader. I noticed that there is no Makefile in the doc/ directory, so I intended to build it by myself:

$ sphinx-build -b epub . build/

To make it work, I had to install the nbsite and the pydata-sphinx-theme packages first. However, I got the following error message:

Sphinx error:
master file /home/zoltan/Downloads/param/doc/index.rst not found

Makes sense, as the is a Markdown file. Renaming it to .rst worked, but it messed up the formatting (not the same result as on the website). How did you achieve the resulting HTML build seen on

Thank you.

Hi @CsatiZoltan !

The source of truth for how the documentation is built in the end is in the Github action that is triggered when the maintainers want to build and deploy a new version of the site.

You can have a look at the different steps of this docs workflow. It includes installing graphviz, nbsite, param its doc dependencies (pip install param[doc] ...), copying the notebooks to another folder and finally executing nbsite.

I’d suggest you to first try to reproduce all these steps locally. If it succeeds, you should have a new folder called builtdocs containing the static (a bunch of HTML files). When you’re done with that, you could then try to generate the documentation in EPUB format, but I can’t help you much for that (have never done it).

Let the community know if you succeed! :slight_smile:

Thank you. In the meantime, I read the HTML version online. Nevertheless, I tried the process for curiosity.
From the link you sent, it turns out that the HTML is built by nbsite, which internally calls Sphinx. I had to install it locally (line 42) to make it work.

So I could build the HTML version on my machine using line 46. However, I did not find EPUB as an output option for nbsite, which is logical as it is meant to be a static site generator.