Tidy up settings in docs/ from initial templating

[AA-Turner]

This removes a lot of commented code from conf.py, and removes the template makefiles

A

[AA-Turner]

I also noticed docs/_static just contained Jupyter images, so I have removed that here too.

[CAM-Gerlach]

With regards to the removals in the conf.py file, I can understand eliding stuff this repo will never use, like the output sections for man pages, epub, etc, but is there a reason to remove options that could plausibly be used in the future, and most of the descriptive comments, even for the options we are using? Space is not at a premium here, and in-use options are clearly indicated by the syntax highlighting, so I'm not sure the simple desire for concision justifies the removal of settings and comments that could be helpful to others in the future.

(Minor copyediting nit, since it will become the commit message with a squash merge—just like with dashes and hyphens, always use an balanced number of spaces (usually zero) on either side)

Sidenote: @encukou It would be helpful for docs community members (or whatever we're officially called) to have at least triage access to this repo, to be able to assign themselves to issues, tag reviewers on PRs, fix titles, manage labels, etc.

[AA-Turner]

I'm not sure the simple desire for concision justifies the removal of settings and comments that could be helpful to others in the future.

I remember a similar discussion for the Sphinx template file iteself. The argument I personally subscribe to is (a) that the comments are clearly for initially filling in the values ("Do X" rather than "X does") and as such at least should be updated to a descriptive style, and (b) those updating these values should look to the official Sphinx documentation, and comments in the source can lead one into a trap where you don't bother and then waste more time as you take the comment as authoritative, whereas it may be out of date, oversimplify, or just is wrong.

(Minor copyediting nit, since it will become the commit message with a squash merge—just like with dashes and hyphens, always use an balanced number of spaces (usually zero) on either side)

What's this referring to, sorry?

A

[CAM-Gerlach]

(a) that the comments are clearly for initially filling in the values ("Do X" rather than "X does") and as such at least should be updated to a descriptive style

Right, but the nominal conventional style is for comments to be imperative, albeit with the "thing" being described as the subject of the sentence rather than the user—that aside, the main point is the substantial loss of information in the comments, in whatever phrasal form one prefers.

(b) those updating these values should look to the official Sphinx documentation, and comments in the source can lead one into a trap where you don't bother and then waste more time as you take the comment as authoritative, whereas it may be out of date, oversimplify, or just is wrong.

True; that's a good point, as these files can drift out of date and be a real chore to update—I've faced that firsthand with various config files like this. On the other hand, at least within a major version, one would think compatibility constraints would entail at least these high-level descriptions still being accurate, i.e. an existing option changing syntax or semantics within a major version would be a significant backward-compatibility breakage that would be precluded by semver and most compatibility policies.

What's this referring to, sorry?

"docs/ settings [sic]" in the PR title, sorry, which becomes the squashed commit summary by default

[AA-Turner]

docs/ settings

Would "Tidy up docs/ settings from initial templating" or "Tidy up settings in docs/ from initial templating" be better?

A

[CAM-Gerlach]

I'm 👍 on either one, thanks

[pradyunsg]

This is a non-blocking suggestion: In the conf.py file, mirror the sections in Sphinx’s documentation, separating sections with a separator and adding relevant URLs for each section.

See https://github.com/pradyunsg/installer/blob/main/docs/conf.py for what this looks like, in practice. sphinx-doc/sphinx#10056 has me trying to convince Sphinx maintainers to change the default conf.py template to this style.

[CAM-Gerlach]

That's a great suggestion @pradyunsg , and one that dovetails well with @AA-Turner 's reasoning as well—I think that yet again, you've (mostly) convinced me.

I do have one major reservation with your broader proposal, though—I've found time and again that having literal examples of the option keys and values that can be used as a base is often invaluable not only for convenience, but in clarifying ambiguities, lack of clarity and missing/assumed details in the prose description that the tool authors might not even have thought of (which I've been on both sides of).

Unfortunately, this is not consistently present in the Sphinx docs linked to; some options have examples, but the great majority don't. This is a pretty critical loss of information; if sphinx-doc/sphinx#10056 is adopted, the examples for each setting currently present in the sample conf.py should be moved to the Sphinx documentation, if a suitable example is not included already.

Its just that often, edge cases or ambiguity that may seem obvious or implicit to tool maintainers is in fact not so to readers, which examples very often clarify; furthermore, many users learn faster and better by example than by reading a chunk of prose, and they are also much more copyable, to reduce the increased mechanical burden and decreased convenience of not having commented examples in the file.

Perhaps this belongs more on the other thread (since it isn't so critical here in this specific case)?

[encukou]

Hmm, why remove the Makefile? That's what I use to build docs...

---

Sidenote: @encukou It would be helpful for docs community members (or whatever we're officially called) to have at least triage access to this repo, to be able to assign themselves to issues, tag reviewers on PRs, fix titles, manage labels, etc.

I agree, here you go: https://discuss.python.org/t/documentation-triagers/13850

[CAM-Gerlach]

Hmm, why remove the Makefile? That's what I use to build docs...

I debated back and forth as to whether to mention that as well, but ultimately decided not to. It appears the intention of the Sphinx developers, per sphinx-doc/sphinx#5618 , is to remove the auto-generated makefiles, store build options in the config and expose a unified sphinx command instead, which seems to be sort of implemented with python -m sphinx, but not really yet. It appears the "nominal" way to invoke Sphinx locally on this repo is now by running sphinx-autobuild per #25 , or explicit commands as needed anyway in the CIs per #30 . Perhaps @AA-Turner could add a build.py script (making sure to allow passing through options to Sphinx) as on the PEPs repo?

[encukou]

Could we please keep the Makefile until that sphinx command is all there, so I can re-train my fingers once for all the docs repos?
I really don't want to look for bespoke commands in READMEs every time I need to check my changes to some docs.

[AA-Turner]

Could we please keep the Makefile

The Makefile is out of date anyway (references to "TeamCompass"). When you invoke make for docs, what command do you run? (I'm on windows so make is another world).

Adding a makefile that passes through to a python script may be the best of both, allowing easy invocation for windows users too.

A

[CAM-Gerlach]

make html, normally (I have make through msys and R dev tools). There's also a make.bat for windows CMD.

[AA-Turner]

I added a simple make.py script and corresponding Makefile; both in the top level so one doesn't need to cd docs before building the documentation.

A

[pradyunsg]

If the problem is the fact that the project name says TeamCompass, you can fix that in a +1/-1 change. Similarly, if you want to have top level Makefile, you can set SOURCEDIR to something other than ..

I'm not sure we need to be creating a custom Python file that imports things, hardcodes python3 and all the things that come with that. I think it's a red herring to try to create our own solution for having a Makefile instead of using what Sphinx generates out of the box as-is.

While I think cleaning up the conf.py file is a good idea; I'm not too sure that it's a good idea to replace/rework the default Sphinx Makefile with something bespoke.

[AA-Turner]

hardcodes python3

In the past when I've used python, reviewers have said to use python3 as of problems with some unix things.

I hadn't realised that this was the default makefile (again, I don't use them) -- would it be better to simply not touch the files at all in this change? People feel rather strongly about them, it seems!

A

[AA-Turner]

Reverted the makefile changes; added comments to conf.py.

A

[encukou]

LGTM, are there any blockers?

[AA-Turner]

None I'm aware of.

A

[CAM-Gerlach]

LGTM, thanks @AA-Turner