-
Notifications
You must be signed in to change notification settings - Fork 93
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
Use links to appendices' commands. #3037
Conversation
One problem with this approach is that the rendered link text displays the section text, which normally is not the same as |
I'm afraid I have no Sphinx-Fu yet; maybe @oliver-sanders or @sadielbartholomew can comment. |
Sphinx encourages you to document objects in a structured manner. tldrIdeally we should use the standard Sphinx approach using the Sphinx DomainsWhen we document a Python function, rather than doing it in plain text like this: Take a look at :ref:`my_function`.
.. _my_function:
``my_function(arg1)``
---------------------
Description of function.
arg1
Description of arg1. We instead use the Python "domain" which is prefixed Take a look at :py:function:`my_function`.
.. py:function:: my_function(arg1)
Description of function.
:param arg1: Description of arg1. Sphinx domains provide metadata about the thing we are documenting, this can be used by the template for presentation but these objects can also be shared between different Sphinx projects. For example we could do the following in the Rose documentation: Take a look at the :py:class:`cylc.scheduler.Scheduler` class. The Standard DomainFor command line programs Sphinx provides the standard domain e.g: On the command line use the :program:`cylc` executable.
.. program:: cylc
A CLI utility for working with, inspecting and running Cylc suites.
There are Sphinx extensions which can automatically do this for CLI's implemented in How Rose Does ItRose does it the wrong way (because we were stuck with https://github.com/metomi/rose/blob/2019.01.0/sphinx/ext/auto_cli_doc.py |
🤓 I'll have to consult the sphinx manual a do a bit of training later. Really feeling like a young grasshopper here.
Hmmm, do you think we can improve the current approach, or would it be a broader change for later?
Anything but Thanks for the detailed explanation @oliver-sanders! I will re-read it later this week, especially the part about domains. |
The big bit of work here is going through the Cylc user guide and making changes like this: - Then run the ``cylc scan`` command.
+ Then run the :program:`cylc scan` command. This shouldn't change no matter how we generate the CLI stuff, whether via an |
Shall we punt this to an issue with #2972 as a dependency? |
OK, from a quick re-read above, @kinow 's fix here doesn't render the link as we want, and it's a bigger job to do it properly ... so I'll close this and create an issue dependent on #2972 as @oliver-sanders suggests. |
A few days ago there was a discussion about dropping the
cylc $COMMAND
documentation, where we decided to keep it.Today while I was reading our documentation for external triggers, I noticed a part that says
And thought since we have documentation for what
cylc suite-state --help
prints, we could simply link to it? I tried a very simple:ref:
command-suite-state`` but that did not work, giving me the error:Being quite novice at Sphinx-Fu, I tried to do exactly as Sphinx's error message suggested, and moved the link before the section header in
make-commands.sh
. Not sure if the other way was intentional, or if I am breaking anything.Tested locally generating with
cylc make-docs
.