Development guide outdated

[ofek]

Describe the bug

Essentially, in python/peps#1577 we're simply trying to confirm that adding code highlighting to PEPs works but we cannot build the site to confirm using https://pythondotorg.readthedocs.io/install.html

We get errors such as:

django.db.utils.OperationalError: could not connect to server: No such file or directory
        Is the server running locally and accepting
        connections on Unix domain socket "/var/run/postgresql/.s.PGSQL.5432"?

Desktop (please complete the following information):

• OS: Windows 10 and Ubuntu 18.04

Additional context

[ofek]

cc @ned-deily @di

Hello! When one of you get a chance, could you please try building with python/peps#1577? We're simply trying to add code highlighting to PEPs.

[di]

Not sure why I'm being tagged here. But! I was curious so I took a look.

I had no problem getting this to run locally, did you follow the createdb pythondotorg ... step listed at https://pythondotorg.readthedocs.io/install.html?

I built your branch with make and make package after installing pygments locally. I then used that artifact when running pythondotorg locally.

I couldn't find any PEPs which this added syntax highlighting for, though. Is there a PEP in particular that I should look at?

I think a first step would be verifying that building a PEP with pygments installed actually produces different HTML. I think once that's confirmed working then this should work fine.

[hugovk]

There aren't any current PEPs with syntax highlighting. Any PRs which added it had to revert it (e.g.
python/peps#119, python/peps#229, python/peps#1571, python/peps#1574, python/peps#1595) because pygments is missing from the CI.

python/peps#1577 is the one to look at, which adds pygments to the CI.

A review of that (python/peps#1577 (comment)) asks to check the deploy still works over here. Hence this issue.

Although I doubt a change to .travis.yml over there would affect anything here.

Perhaps python/peps#1577 should also add some syntax highlighting to a single PEP?

[hugovk]

I think a first step would be verifying that building a PEP with pygments installed actually produces different HTML. I think once that's confirmed working then this should work fine.

I can do this locally.

This change:

diff --git a/pep-0631.rst b/pep-0631.rst
index da638e3b..7dc1d107 100644
--- a/pep-0631.rst
+++ b/pep-0631.rst
@@ -24,7 +24,7 @@ All dependency entries MUST be valid `PEP 508 strings`_.

 Build backends SHOULD abort at load time for any parsing errors.

-::
+.. code-block:: python

     from packaging.requirements import InvalidRequirement, Requirement

Produces this change in HTML:

63,64c63,64
< <pre class="literal-block">
< from packaging.requirements import InvalidRequirement, Requirement
---
> <pre class="code python literal-block">
> <span class="keyword namespace">from</span> <span class="name namespace">packaging.requirements</span> <span class="keyword namespace">import</span> <span class="name">InvalidRequirement</span><span class="punctuation">,</span> <span class="name">Requirement</span>
66c66
< ...
---
> <span class="operator">...</span>
68,71c68,71
< try:
<     Requirement(entry)
< except InvalidRequirement:
<     # exit
---
> <span class="keyword">try</span><span class="punctuation">:</span>
>     <span class="name">Requirement</span><span class="punctuation">(</span><span class="name">entry</span><span class="punctuation">)</span>
> <span class="keyword">except</span> <span class="name">InvalidRequirement</span><span class="punctuation">:</span>
>     <span class="comment single"># exit</span>

Pygments must already be installed or:

$ make pep-0631.html
pep-0631.rst (text/x-rst) -> pep-0631.html
pep-0631.rst:27: (WARNING/2) Cannot analyze code. Pygments package not found.
Traceback (most recent call last):
...
docutils.utils.SystemMessage: pep-0631.rst:27: (WARNING/2) Cannot analyze code. Pygments package not found.
make: *** [pep-0631.html] Error 1

[ofek]

Thank you both! So all that needs to be done is adding pygments to the CI of both repos?

[di]

I don't think it needs added here. From what I can tell, the python/peps CI job just builds all PEPs, tars them up and pushes them to S3. This repo doesn't do any actual rendering of PEPs.

[di]

That said, we might need to add some CSS so the classes that pygments produces show up correctly.

[hugovk]

That said, we might need to add some CSS so the classes that pygments produces show up correctly.

I found PR #1063 to add CSS colouring, but it was closed in 2017 as the plan was to use RtD instead. Also in 2017 Brett suggested re-opening it as the RtD move was going slowly.

In 2020 the RtD move is still going slowly, so I've rebased #1063 and re-opened it as #1638.

[ofek]

Thanks!!!