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
_______________________________________________ Pulp-dev mailing list Pulp-dev@redhat.com https://www.redhat.com/mailman/listinfo/pulp-dev