Fix the docs build! + Remove unsupported options from Sphinx config + Update deps + add rst_prolog

[melroy89]

@k0ekk0ek Problem found!

• I was missing the following config in the conf.py.in file:

  rst_prolog = ".. |version| replace:: @version@"

  Output is now correct:
  

• Updated directly to the latest version of Sphinx (v8).

  • Also updated sphinx-tabs, etc.

• I also explicitly pinned the version of sphinx-substitution-extensions, since it was installing 2022 for some reason (instead of 2024)

• Extend RELNOTES & ChangeLog

---

Plus I saw some warnings, so hence this PR to fix those as well:

• Remove unsupported theme option display_version , see: Latest released version asserts "unsupported theme option 'display_version' given" Warning readthedocs/sphinx_rtd_theme#1623 (comment)
• Remove html_theme_path, this is not required anymore. See: https://sphinx-rtd-theme.readthedocs.io/en/latest/changelog.html

Original build output:

....
mandoc -T html -O fragment nsd-control.8 > doc/manual/manpages/nsd-control.8.html
sed -i '/<table class="\(head\|foot\)">/,/<\/table>/ d' doc/manual/manpages/nsd-control.8.html
sphinx-build -M html ./doc/manual doc/manual -N -q
WARNING: Calling get_html_theme_path is deprecated. If you are calling it to define html_theme_path, you are safe to remove that code.
WARNING: unsupported theme option 'display_version' given
/media/melroy/Data/Projects/nsd/doc/manual/catalog-zones.rst:46: WARNING: unknown document: 'running/xot'
/media/melroy/Data/Projects/nsd/doc/manual/configuration.rst:15: WARNING: unknown option: '-c'
/media/melroy/Data/Projects/nsd/doc/manual/configuration.rst:214: WARNING: unknown option: '-c'
/media/melroy/Data/Projects/nsd/doc/manual/installation.rst:118: WARNING: unknown option: '-V'
/media/melroy/Data/Projects/nsd/doc/manual/installation.rst:130: WARNING: unknown option: '-d'
/media/melroy/Data/Projects/nsd/doc/manual/installation.rst:130: WARNING: unknown option: '-V'
/media/melroy/Data/Projects/nsd/doc/manual/running/interfaces.rst:4: WARNING: unknown option: '-4'
/media/melroy/Data/Projects/nsd/doc/manual/running/interfaces.rst:4: WARNING: unknown option: '-6'
/media/melroy/Data/Projects/nsd/doc/manual/running/interfaces.rst:9: WARNING: unknown option: '-a'

[melroy89]

Fun fact, it's PR 404 not found.

[k0ekk0ek]

Thanks for the patches @melroy89! I pushed minor corrections to doc/ChangeLog as that file is more-or-less about which developer updated/reviewed the work and while you did the work, you technically did not merge the changes. You'll get all the kudos though.

[k0ekk0ek]

Right, I don't know how to handle this situation now. I'll let another dev handle it. Still, thank you for the work. @wtoorop, @wcawijngaards, @gthess, care to pitch in here? I'm not against @melroy89 stating his name in doc/ChangeLog, but I'm assuming that it's also about which developer employee reviewed/merged?

[melroy89]

Right, I don't know how to handle this situation now. I'll let another dev handle it. Still, thank you for the work. @wtoorop, @wcawijngaards, @gthess, care to pitch in here? I'm not against @melroy89 stating his name in doc/ChangeLog, but I'm assuming that it's also about which developer employee reviewed/merged?

Sorry if I got that wrong. I'm new here, but I thought the changelog is stated who did the change. Right? I'm confused indeed.

[melroy89]

@k0ekk0ek anyhow I changed it back to jeroen if that is how the changelog works. 😅

[k0ekk0ek]

This works just fine, thanks @wtoorop! @melroy89, are you happy with the outcome? (The release notes is where we usually thank contributors (in my experience), and we still can, but this works too)

[melroy89]

Yes please merge 😁 so the docs is fixed again.

[k0ekk0ek]

Great! Thanks for figuring out the |version| stuff in the documentation 👍 Definitely a nice improvement.

[melroy89]

No problem.

The warnings about WARNING: unknown option: '-c' you see, are all the places in the rst files where :option: is used actually. Which I think allows us to define some page with the available options? Which is either not in place now, or incomplete.

Do we need to extend: https://nsd.docs.nlnetlabs.nl/en/latest/reference/configure-options.html ? Or introduce another page?