Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: remove dune:action directive #10152

Merged
merged 4 commits into from
Mar 5, 2024
Merged

Conversation

emillon
Copy link
Collaborator

@emillon emillon commented Feb 27, 2024

The goal of this PR is to remove the custom python code to handle dune:
directives.

This plugin (in doc/exts/sphinx_dunedomain.py) defines directives that do several things:

  • they generate nice markup that describe what we're documenting (the headers with blue or gray backgroud)
  • they support cross-references
  • they generate an index

But, this is too complicated for our use case:

  • cross-references are unnecessary now that we have one document per action
  • the index was not linked, but we now have a nicer one in reference/actions/index
  • crucially, there's a describe directive in Sphinx that generates the same markup as the one we were generating.

So this PR does 2 things:

  • switch from the high-level dune:action:: to a low-level describe:: (which renders identically)
  • remove the now unused support code in sphinx_dunedomain.py

@emillon emillon added the docs Documentation improvements label Feb 27, 2024
@emillon emillon requested a review from ElectreAAS February 27, 2024 14:08
@emillon
Copy link
Collaborator Author

emillon commented Feb 27, 2024

(as followup PRs I have similar ones that do the same for dune:field and dune:stanza, thus removing sphinx_dunedomain completely)

Signed-off-by: Etienne Millon <me@emillon.org>
Signed-off-by: Etienne Millon <me@emillon.org>
@emillon emillon force-pushed the doc-remove-dune-action branch from 3c8574a to 2b870cd Compare February 28, 2024 15:26
@ElectreAAS
Copy link
Collaborator

While this looks obviously correct, and I'm generally in favor of removing python code, do you know more about the why was this code added there in the first place? And what do you mean by unneeded cross-references here?

@emillon
Copy link
Collaborator Author

emillon commented Mar 5, 2024

I wrote the python code in question. At the time I thought that this was the only way of getting this kind of markup (I didn't know about describe::). Indices and cross-references are nice sphinx features, but they're not really required: instead of using a xref to link to the cat action, we can just link to the cat document (now that it exists).

@emillon emillon merged commit f04be44 into ocaml:main Mar 5, 2024
24 of 26 checks passed
@emillon
Copy link
Collaborator Author

emillon commented Mar 5, 2024

Thanks!

@emillon emillon deleted the doc-remove-dune-action branch March 5, 2024 15:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation improvements
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants