Doxygen improvements #2476

lmoureaux · 2024-12-29T16:17:34Z

The aim of this PR is to add the Doxygen output to our ReadTheDocs website.

Once merged one can write:

:freeciv21:`function_name`

and get a link to that function in the latest documentation. Unfortunately it's not possible to do it for PR builds, the link prefix needs to be fixed (you can replace it manually though).

Example from this PR: https://longturn--2476.org.readthedocs.build/en/2476/Doxygen/fcintl_8h.html

Note: ~~Currently Doxygen is not working~~ (fixed)

Closes longturn#1186.

On Ubuntu 24.04.

Make it more Freeciv21-specific and enable the sidebar to speed up navigation.

The documentation will be located at: https://longturn.readthedocs.io/en/latest/Playing/index.html

We need a special version of doxylink from my fork. I opened a PR but it's relatively large and upstream doesn't seem very active, so we can use the fork for now.

This includes a link in the sidebar and most code references in the Coding section.

jwrober

We should also update the docs style guide to describe when to use the new freeciv21 interpreted text role. I'm sure there is more. I want to test locally. Is there a needed change to requirements.txt? Another package to install for doc authors?

jwrober · 2024-12-30T01:55:48Z

docs/Coding/index.rst

@@ -17,4 +17,5 @@ architected.
  logging.rst
  network-protocol.rst
  scorelog.rst
+  Doxygen Documentation <https://longturn.readthedocs.io/en/latest/Doxygen>


This won't work for local builds. Can we use a :doc: link instead?

Unfortunately not, Sphinx doesn't know about the Doxygen pages.

What about a relative URI vs absolute?

Sphinx tries to find a rst file and complains that it's not there. The only workaround I found is to create a dummy rst, then replace the generated HTML.

is the complaint a warning or fatal? If a warning, I'm personally fine. We have some warnings already due to how the man pages are done.

It cannot resolve the reference and doesn't produce a link at all...

jwrober · 2024-12-30T02:00:00Z

docs/requirements.txt

@@ -1,3 +1,6 @@
 sphinx<7.2  # See #2023
 sphinx_rtd_theme
 sphinx_last_updated_by_git
+
+# Optional: link Doxygen docs from sphinx
+git+https://github.com/lmoureaux/doxylink


I'm not sure we should rely on something external to the Longturn set of repos

I created a PR upstream, but it will take some time for them to merge and release. It's not a particularly small one...

Ok. How about an update to the comment to the same so we know we need to change to upstream at some point in the future?

We can also fork it within the org.

Meanwhile my PR upstream has been reviewed.

This is needed for doxygen.

lmoureaux · 2024-12-30T02:49:31Z

To produce the Doxygen docs locally, run:

cmake --build build --target docs

from the root of the source tree. The doc index gets written to doxygen/html/index.html.
This also builds the Sphinx docs, but cross-referencing won't work.

To build the cross-linked Sphinx docs, you need a virtualenv:

python -m virtualenv venv
source venv/bin/activate
pip install -r docs/requirements.txt

Then build outside of CMake:

sphinx-build docs build/docs/

I'm not sure where and how to explain this in the docs. The setup is definitely tricky.

lmoureaux · 2024-12-30T03:02:10Z

I could change CMake to create the virtualenv and run Sphinx inside it, but I don't like when build systems try to pull packages from random internet locations.

jwrober · 2024-12-30T03:07:42Z

docs/CMakeLists.txt

+  # command does it. The output is a dummy one so the command always runs.
+  # doxygen has some level of caching so it doesn't take that long, and
+  # collecting a list of all source files would be cumbersome.
+  add_custom_command(OUTPUT dummy-doxygen


I would not call this "dummy", I would simply call this what it is. You are building doxy. I'd prefer it be in /build tho, vs the root so we don't need another .gitignore.

I would not call this "dummy", I would simply call this what it is. You are building doxy.

The output is really a dummy one. CMake expects a file there, but I give something that never gets produced to force running doxygen every time. This is what the comment above tries to explain.

I'd prefer it be in /build tho, vs the root so we don't need another .gitignore.

The output folder is set in the Doxyfile and cannot be overridden in the Doxygen command line. I cannot easily change it because I need to run doxygen in the RTD builder, and installing all the dependencies there would be overkill. Maybe I can come up with some CMake magic to configure the Doxyfile on RTD...

jwrober · 2025-01-04T19:29:23Z

Testing locally, having challenges. As we move through this, we definitely need to document it all in docs/Getting/compile.rst once we get everything figured out.

lmoureaux added 5 commits December 29, 2024 17:23

Fix Doxygen warnings

abcd180

Closes longturn#1186.

Update Doxygen config for 1.9.8

e08b6d3

On Ubuntu 24.04.

Tweak the Doxygen output a bit

20b9797

Make it more Freeciv21-specific and enable the sidebar to speed up navigation.

Add the Doxygen output to .gitignore

72ea228

Host the Doxygen documentation on readthedocs

1c860d7

The documentation will be located at: https://longturn.readthedocs.io/en/latest/Playing/index.html

lmoureaux force-pushed the feature/doxygen branch from a2089f3 to 1c860d7 Compare December 29, 2024 16:23

lmoureaux added 2 commits December 30, 2024 00:19

Configure doxylink to cross-link from Sphinx to Doxygen

6c59a1b

We need a special version of doxylink from my fork. I opened a PR but it's relatively large and upstream doesn't seem very active, so we can use the fork for now.

Add links from Sphinx to Doxygen

f42646f

This includes a link in the sidebar and most code references in the Coding section.

lmoureaux marked this pull request as ready for review December 30, 2024 00:05

lmoureaux requested a review from jwrober December 30, 2024 00:05

jwrober reviewed Dec 30, 2024

View reviewed changes

Readthedocs: install graphviz

399cd5f

This is needed for doxygen.

lmoureaux force-pushed the feature/doxygen branch from eb172cb to 399cd5f Compare December 30, 2024 02:35

Add :freeciv21: to the style guide

176e507

jwrober reviewed Dec 30, 2024

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Doxygen improvements #2476

Doxygen improvements #2476

lmoureaux commented Dec 29, 2024 •

edited

Loading

jwrober left a comment

jwrober Dec 30, 2024

lmoureaux Dec 30, 2024

jwrober Dec 30, 2024

lmoureaux Dec 30, 2024 •

edited

Loading

jwrober Dec 30, 2024

lmoureaux Dec 30, 2024

jwrober Dec 30, 2024

jwrober Dec 30, 2024

lmoureaux Dec 30, 2024

jwrober Dec 30, 2024

lmoureaux Dec 30, 2024

lmoureaux Dec 30, 2024

lmoureaux commented Dec 30, 2024 •

edited

Loading

lmoureaux commented Dec 30, 2024

jwrober Dec 30, 2024

lmoureaux Dec 30, 2024 •

edited

Loading

jwrober commented Jan 4, 2025 •

edited

Loading

Doxygen improvements #2476

Are you sure you want to change the base?

Doxygen improvements #2476

Conversation

lmoureaux commented Dec 29, 2024 • edited Loading

jwrober left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmoureaux Dec 30, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lmoureaux commented Dec 30, 2024 • edited Loading

lmoureaux commented Dec 30, 2024

Choose a reason for hiding this comment

lmoureaux Dec 30, 2024 • edited Loading

Choose a reason for hiding this comment

jwrober commented Jan 4, 2025 • edited Loading

lmoureaux commented Dec 29, 2024 •

edited

Loading

lmoureaux Dec 30, 2024 •

edited

Loading

lmoureaux commented Dec 30, 2024 •

edited

Loading

lmoureaux Dec 30, 2024 •

edited

Loading

jwrober commented Jan 4, 2025 •

edited

Loading