Styling project command line options

[philderbeast]

Related to #12144, renders the project command line options with a command line style. The -- preceded options are parsed out or you can optionally use a :command-line-options: directive.

• Before

• After

Note

If this is acceptable and enough to show command line options (the $ prefix indicating this), then we might remove some of the text describing the same thing. In other words, instead of fixing #12144 by using the plural, we could remove a lot of that text where it adds no value.

Warning

I used Copilot to write the *.py and *.css changes.

I used sphinx warnings reporting missing references to identify undocumented command line options. I've added these as a new "Undocumented options" section, a fraction of which is shown here:

Having an undocumented section like this gets rid of those missing reference warnings. Also note the enable-*, disable-* items on the same line. This works for linking to references.

---

• Patches conform to the coding conventions.
• Is this a PR that fixes CI? If so, it will need to be backported to older cabal release branches (ask maintainers for directions).

[ffaf1]

I like the change, but 80 new lines of Python, I don't fancy those.

[Bodigrim]

Dunno, I'm rather sceptical about having more Python and more custom CSS, both of which has to be supported in eternity (e. g., if ReadTheDocs makes breaking changes).

[philderbeast]

I like the change, but 80 new lines of Python, I don't fancy those.

Thanks @ffaf1. The line count change is looking better.

[ulysses4ever]

I am fine with extra python and css.

I find sequence like $ --allow-newer confusing and I'd appreciate it if a way around it was found in this PR. In particular I don't see the dollar sign as something that introduced command line options necessarily; plus, an option without an executable name just looks weird, so the whole thing doesn't look remotely close to what you are used to in command line.

[philderbeast]

In particular I don't see the dollar sign as something that introduced command line options necessarily

It is there as a symbol (or key) to introduce a command line option. Of the possible options, I like that symbol the best:

• > (Greater-than sign): Used by Microsoft Windows in the classic Command Prompt (C:>).
• $ (Dollar sign): Used by default in many Unix, Linux, and macOS shells (like Bash and Zsh) for regular users.
• % (Percent sign): Used by default in the Zsh shell on modern macOS versions.
• # (Number sign / Pound): Used to show a root or super-user prompt in Linux and Unix systems.

Are you able to look at the rendered user guide again and see those $ characters more as bullet points, each introducing an item rather than literal command prompts?

[philderbeast]

These new docs link together better than the current latest one does.

To see this in action, look at with-compiler: PATH. Clicking anywhere on the line below with the command line equivalent items goes nowhere but on the rendered docs for this pull request, clicking on any of the command line equivalents take you to that command line option on the cabal commands page¹.

Footnotes

1. Why is this option, --with-compiler, shown with cabal list? I would have thought it more of a cabal build option. ↩

[philderbeast]

Dunno, I'm rather sceptical about having more Python and more custom CSS, both of which has to be supported in eternity (e. g., if ReadTheDocs makes breaking changes).