[Pulp-dev] Thoughts on static-doc-building

[Grant Gainey]

After the discussion in yesterday's pulp-team-mtg about building docs, and
in honor of docs-day, I have been looking into what it would take to make
updating our docs not require a dev-environment installation.

Building docs includes building the REST API docs, which wants to talk to a
running pulp-server. Sphinx also relies on django, which relies on
settings, which are Unhappy if you're not on an installed pulp-instance.
When all you want to do is edit the static pages, this is all overkill.

As a (gross, brute-force) experiment, I did the following in my environment:

   1. Create a virtual-env (you don't have to do this, although it is good
   practice. I'm doing it here to isolate this work from the rest of my
   dev-workstation)
   2. Clone pulpcore
   3. Install doc-requirements
   4. Apply the following patch to the environment:
   diff --git a/docs/Makefile b/docs/Makefile
   index dba1b115c..9fe952dab 100644
   --- a/docs/Makefile
   +++ b/docs/Makefile
   @@ -2,7 +2,7 @@
    #

    # You can set these variables from the command line.
   -SPHINXOPTS           = -W  # turn warnings into errors
   +SPHINXOPTS           = # -W  # turn warnings into errors
    SPHINXBUILD          = sphinx-build
    PAPER                =
    BUILDDIR             = _build
   diff --git a/docs/conf.py b/docs/conf.py
   index af6e0e79e..91828806e 100644
   --- a/docs/conf.py
   +++ b/docs/conf.py
   @@ -29,7 +29,7 @@ import pulpcore
    os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings"

    import django
   -django.setup()
   +#django.setup()

    # -- General configuration
   -----------------------------------------------------

   5. Build the docs using the '*dirhtml*' target, ignoring a flurry of
   warnings/errors (dirhtml skips trying to get the REST api.json)
   6. Start a local webserver in the directory
   7. Look at the built docs at http://localhost:8010

The exact commands on my F32 box were these:

mkvirtualenv docs
workon docs
git clone https://github.com/pulp/pulpcore.git
cd pulpcore/
pip install -r doc_requirements.txt
git apply - <<PATCH
> diff --git a/docs/Makefile b/docs/Makefile
> index dba1b115c..9fe952dab 100644
> --- a/docs/Makefile
> +++ b/docs/Makefile
> @@ -2,7 +2,7 @@
>  #
>
>  # You can set these variables from the command line.
> -SPHINXOPTS           = -W  # turn warnings into errors
> +SPHINXOPTS           = # -W  # turn warnings into errors
>  SPHINXBUILD          = sphinx-build
>  PAPER                =
>  BUILDDIR             = _build
> diff --git a/docs/conf.py b/docs/conf.py
> index af6e0e79e..91828806e 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -29,7 +29,7 @@ import pulpcore
>  os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings"
>
>  import django
> -django.setup()
> +#django.setup()
>
>  # -- General configuration
-----------------------------------------------------
>
> PATCH
cd docs
make dirhtml # ignore the angry errors
cd _build/dirhtml/
python -m http.server 8010


And my newly-build docs are now being served at http://localhost:8010/

How do people feel about cleaning this up and making it an 'official' way
to build docs? Would make it way easier for folk who only want/need to edit
the static pages to make contributions.

Thoughts/brickbats gratefully accepted! :)

G
-- 
Grant Gainey
Principal Software Engineer, Red Hat System Management Engineering
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/pulp-dev/attachments/20201013/fe980f9d/attachment.htm>