Permalink issue in settings.rst documentation

[asweigart]

I'd like to link to individual settings in on the settings.html page produced by settings.rst in the docs folder, but they only appear for settings that don't have a default value. I think this is a ReStructured Text or plugin issue maybe?

For example, the AUTHOR setting does have a P paragraph symbol appear when you hover over it with an anchor link to the AUTHOR setting. It looks like this in settings.rst:

.. data:: AUTHOR

However, the DEFAULT_METADATA setting doesn't have this anchor link appear. It looks like this in settings.rst:

.. data:: DEFAULT_METADATA = {}

It seems that every setting that has an "=" equal sign with a default value is throwing off whatever adds the anchor links. I recommend that we move the default setting into the setting description as a separate sentence.

I'm currently writing a Pelican tutorial and it'd be very helpful if I could link directly to the settings I discuss.

I would be willing to do this work if I see that this project is being actively maintained and someone can accept the PR.

[justinmayer]

Hey Al. We have crossed paths at Python conferences but never properly met. Nice to see you here 👋

I appreciate the offer to address an issue that has indeed been vexing, so thank you for bringing it up and offering to assist.

While I personally think it is clear from the activity here in GitHub that Pelican is indeed actively maintained, of course that is subjective. Your assistance would be welcome, and I would be happy to review the pull request. 😊

[asweigart]

Ah, pardon. I was looking close enough at the repo and discussion forums to see the activity. I'll try to experiment with some designs and figure out a way to get the individual settings to be linkable. Hopefully I can get to it next week. Thanks!

[asweigart]

I'm having some difficulties getting invoke to run the tests and linting check. I ran pip install invoke (is there a reason invoke is not included in the requirements files?) but invoke tests and invoke lint just give me /bin/bash: /Users/al/Library/Application: No such file or directory errors no matter what folder I run it from. Running invoke --help does show that invoke is installed.

Since this is just a one-file doc change, would it be easier to send someone the file I updated? main...asweigart:pelican:docs-fix-settings-anchor

[justinmayer]

That is an odd error. I’ve never seen that one before. Is this inside a new activated Python virtual environment? If so, perhaps try python -m pip install invoke && python -m invoke setup?

[asweigart]

Ah, okay. I think it might have been because I was using Hatch to manage my venv and it stores them under /Users/al/Library/Application Support, and the space in the file path was wrecking something.

I had to run pip install invoke, pdm, and ruff in addition to the requirements files. I didn't find any failures that weren't already there. I don't think the linting checks the .rst files, does it?

I'll go ahead and submit my PR.

[justinmayer]

Linting tools shouldn’t check reST files.

If following the Setting Up the Development Environment documentation isn’t sufficient in some way, PRs to address that would be helpful and appreciated 😊