How to build the documentation?

CsatiZoltan · October 15, 2021, 1:47pm

Hi,

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 index.md 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 https://github.com/holoviz/param/tree/gh-pages?

Thank you.

maximlt · October 23, 2021, 3:50pm

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.

github.com

holoviz/param/blob/master/.github/workflows/docs.yml

name: docs
on:
  push:
    tags:
      - 'v[0-9]+.[0-9]+.[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+a[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+b[0-9]+'
      - 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
  workflow_dispatch:
    inputs:
      target:
        description: 'dev or main'     
        required: true
        default: 'dev'

jobs:
  build_docs:
    name: Documentation
    runs-on: 'ubuntu-latest'
    timeout-minutes: 120

This file has been truncated. show original

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!

CsatiZoltan · October 23, 2021, 5:18pm

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.

github.com

holoviz/param/blob/a10fe2b39e6d7e9533f70dbe84e8644ed4b57c16/.github/workflows/docs.yml#L42

    
      
              python-version: 3.7
          - name: Set output
            id: vars
            run: echo ::set-output name=tag::${GITHUB_REF#refs/*/}
          - name: graphviz
            run: sudo apt install graphviz graphviz-dev
          - name: env setup
            run: |
              python -m pip install pip==21.0.0
              python -m pip install nbsite --pre
              python -m pip install -e .[doc] --use-feature=fast-deps --use-deprecated=legacy-resolver
          - name: build docs
            run: |
              cp examples/user_guide/*.ipynb doc/user_guide/
              python -m nbsite build --org holoviz --project-name param
          - name: Deploy dev
            uses: peaceiris/actions-gh-pages@v3
            if: (github.event.inputs.target == 'dev' || contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc'))
            with:
              personal_token: ${{ secrets.ACCESS_TOKEN }}
              external_repository: pyviz-dev/param

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.