On Sun, 2022-04-03 at 03:59 -0700, Tomer wrote: > Hello, > > I'm trying to use Sphinx to automatically generate documentation for a command > line tool written in Python using Click. > I'm using the sphinx-click plugin for this, but I'm having trouble figuring > out how to cross-reference specific types of functions - namely commands and > command groups.
Hey, Just FYI, sphinx-click is an extension, which means the sphinx-users group generally isn't the best place to ask questions like this. You're better off using the issue tracker for the project. With that said, I'm the maintainer of sphinx-click and subscribe to this list so perhaps you've got lucky :) > I can reference options using :option:`group_name-command_name -option_name`, > and I can reference environment variables using :ref:`DisplayText <group- > command-option-envvar>` (doesn't seem to work without supplying a name, as > written here), but despite doing much trial and error I can't find how to > reference command or command groups. > The only solution I've found is HTML-specific, by using a direct link like > `DisplayText <group-page.html#group-command>`_ - or `DisplayText <#group- > command>`_ if it's on the same page - but that's obviously not a very good > solution. This is actually called out in the documentation [1]: Programs Sphinx currently does not allow you to cross-reference programs. See Sphinx issue #880 for more information. So this is an issue with Sphinx itself that we can't fix. What we _could_ do is add a custom anchor like we now do for environment variables which you could then reference. It would be quite trivial to do and I'd happily welcome a PR. It just hasn't been done yet. Cheers, Stephen [1] https://sphinx-click.readthedocs.io/en/latest/usage/#cross-referencing PS: A more involved PR would involve adding custom roles for all of these so that we could avoid using Sphinx's (somewhat broken) standard domain roles/directives entirely. That's a lot more work though and I suspect this would require some good working Sphinx knowledge. > > Seeing as the table of contents entry does reference these things, I figure > there's got to be a way to get these references, so I'm hoping someone here > might have an answer for me. > Being able to read the .doctree files to see what all the label names are > might be enough, but I don't know how to do that either. > > Any help would be appreciated. > Thanks in advance! > > > Disclaimer > The information contained in this communication from the sender is > confidential. It is intended solely for use by the recipient and others > authorized to receive it. If you are not the recipient, you are hereby > notified that any disclosure, copying, distribution or taking action in > relation of the contents of this information is strictly prohibited and may be > unlawful. > -- > You received this message because you are subscribed to the Google Groups > "sphinx-users" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to sphinx-users+unsubscr...@googlegroups.com. > To view this discussion on the web visit > https://groups.google.com/d/msgid/sphinx-users/0e383cdc-06ec-4327-8ec4-6b8213daee4bn%40googlegroups.com > . -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/102eb8cfd4e930c27fd374473c0ac33e8f2292bd.camel%40that.guru.
