<div dir="ltr">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.<div><br></div><div>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.</div><div><br></div><div>As a (gross, brute-force) experiment, I did the following in my environment:</div><div><ol><li>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)</li><li>Clone pulpcore</li><li>Install doc-requirements</li><li>Apply the following patch to the environment:<br><font face="monospace" size="1">diff --git a/docs/Makefile b/docs/Makefile<br>index dba1b115c..9fe952dab 100644<br>--- a/docs/Makefile<br>+++ b/docs/Makefile<br>@@ -2,7 +2,7 @@<br> #<br> <br> # You can set these variables from the command line.<br>-SPHINXOPTS           = -W  # turn warnings into errors<br>+SPHINXOPTS           = # -W  # turn warnings into errors<br> SPHINXBUILD          = sphinx-build<br> PAPER                =<br> BUILDDIR             = _build<br>diff --git a/docs/conf.py b/docs/conf.py<br>index af6e0e79e..91828806e 100644<br>--- a/docs/conf.py<br>+++ b/docs/conf.py<br>@@ -29,7 +29,7 @@ import pulpcore<br> os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings"<br> <br> import django<br>-django.setup()<br>+#django.setup()<br> <br> # -- General configuration -----------------------------------------------------</font><br> <br></li><li>Build the docs using the '<b>dirhtml</b>' target, ignoring a flurry of warnings/errors (dirhtml skips trying to get the REST api.json)</li><li>Start a local webserver in the directory</li><li>Look at the built docs at <a href="http://localhost:8010">http://localhost:8010</a></li></ol></div><div>The exact commands on my F32 box were these:</div><blockquote style="margin:0 0 0 40px;border:none;padding:0px"><div><font face="monospace" size="1">mkvirtualenv docs</font></div><div><font face="monospace" size="1">workon docs</font></div><div><font face="monospace" size="1">git clone <a href="https://github.com/pulp/pulpcore.git">https://github.com/pulp/pulpcore.git</a></font></div><div><font face="monospace" size="1">cd pulpcore/</font></div><div><font face="monospace" size="1">pip install -r doc_requirements.txt</font></div><div><font face="monospace" size="1">git apply - <<PATCH</font></div><div><font face="monospace" size="1">> diff --git a/docs/Makefile b/docs/Makefile</font></div><div><font face="monospace" size="1">> index dba1b115c..9fe952dab 100644</font></div><div><font face="monospace" size="1">> --- a/docs/Makefile</font></div><div><font face="monospace" size="1">> +++ b/docs/Makefile</font></div><div><font face="monospace" size="1">> @@ -2,7 +2,7 @@</font></div><div><font face="monospace" size="1">>  #</font></div><div><font face="monospace" size="1">>  </font></div><div><font face="monospace" size="1">>  # You can set these variables from the command line.</font></div><div><font face="monospace" size="1">> -SPHINXOPTS           = -W  # turn warnings into errors</font></div><div><font face="monospace" size="1">> +SPHINXOPTS           = # -W  # turn warnings into errors</font></div><div><font face="monospace" size="1">>  SPHINXBUILD          = sphinx-build</font></div><div><font face="monospace" size="1">>  PAPER                =</font></div><div><font face="monospace" size="1">>  BUILDDIR             = _build</font></div><div><font face="monospace" size="1">> diff --git a/docs/conf.py b/docs/conf.py</font></div><div><font face="monospace" size="1">> index af6e0e79e..91828806e 100644</font></div><div><font face="monospace" size="1">> --- a/docs/conf.py</font></div><div><font face="monospace" size="1">> +++ b/docs/conf.py</font></div><div><font face="monospace" size="1">> @@ -29,7 +29,7 @@ import pulpcore</font></div><div><font face="monospace" size="1">>  os.environ["DJANGO_SETTINGS_MODULE"] = "pulpcore.app.settings"</font></div><div><font face="monospace" size="1">>  </font></div><div><font face="monospace" size="1">>  import django</font></div><div><font face="monospace" size="1">> -django.setup()</font></div><div><font face="monospace" size="1">> +#django.setup()</font></div><div><font face="monospace" size="1">>  </font></div><div><font face="monospace" size="1">>  # -- General configuration -----------------------------------------------------</font></div><div><font face="monospace" size="1">>  </font></div><div><font face="monospace" size="1">> PATCH</font></div><div><font face="monospace" size="1">cd docs</font></div><div><font face="monospace" size="1">make dirhtml # ignore the angry errors</font></div><div><font face="monospace" size="1">cd _build/dirhtml/</font></div><div><font face="monospace" size="1">python -m http.server 8010</font></div></blockquote><div><br></div><div>And my newly-build docs are now being served at <a href="http://localhost:8010/">http://localhost:8010/</a></div><div><br></div><div>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.</div><div><br clear="all"><div>Thoughts/brickbats gratefully accepted! :)</div><div><br></div><div>G</div>-- <br><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Grant Gainey</div><div>Principal Software Engineer, Red Hat System Management Engineering</div></div></div></div></div></div></div>