KcushTrends .com On Wed, 6 Apr 2022, 17:14 Tomer, <tomer.godin...@redis.com> wrote:
> Hi Stephen, > > Pardon the late reply; I wanted to make some decisions and try things out > before getting back to you. > > I've forked the sphinx-click repository and made a few modifications > locally. > Namely what I've added is: > > - Anchors for groups and commands in the same dash-separated form as > the rest (group, group-command). > - Extra anchors for options and arguments to conform to the same > standard (`group-command-option`, `group-command-arg`) > - Namely if you have an option with multiple names, e.g. -v, > --verbose for command `log` in the group `run`, you'll get both > `run-log-v` and `run-log-version`. > - A new :hide-header: flag which hides the title, description and > usage. If used with the ":nested: none" setting, this would produce an > empty output, so in that specific case I made it only remove the title. > - A new nesting value which I very poorly named ":nested: complete" > for lack of a better idea (suggestions are welcome). It's basically like > the ":nested: full" setting but it also includes the short > descriptions from ":nested: short" before it shows the full details. > See attached screenshot below for an example. > > I only have it working with my little experimentation project though. > Haven't done any proper testing yet. > > Aside from that, I've written a small module to facilitate generating > references using the added anchors to the documentation from within the > docstrings of the CLI commands themselves. > I don't know if that's of any interest to you - if so you're welcome to > read on. > > I'll first explain why. > I saw that if I put something like the following in a docstring for an > example "starter order-soup" command: > > Soup goes great with :ref:`meat <main-order-meat>`, you know (just be > sure to specify a good :option:`dish <main order-meat -dish>`). > > It works and generates the references. > However, as you would expect, if you then ran the CLI tool and typed "cli > starter order-soup --help", you would get exactly the above text, which > is naturally not something you want to see in a CLI help message. > > So I wrote something that wraps Click's command decorators, parses the > docstrings of each command and replaces the references with suitable text. > I made it so that you can set some environment variable to say that you're > currently building the documentation - if so then it replaces the text with > references, otherwise it removes everything but the name. > (By the way, do you know if there's a way to detect whether we're running > Sphinx or the actual CLI without using an environment variable like that? > That'd be nicer.) > Since I transform the text in both instances I can be more flexible in > format, so I made it so that you can type any of the following: > :type_of_reference:`Display Name Here <reference_path>` > :type_of_reference:`reference_path` > `Display Name Here <reference_path>` > `reference_path` > and you'll get a reference in Sphinx-generated documents and only the > display names in the CLI itself. > (The "type of reference" bit is to let you choose to use :option: instead > of :ref: since that only works for options but also does some nice > formatting.) > > If any of this is of interest to you I'd love to share it, so please tell > me if so. > > Aside from that, regarding what you said, I do think the documentation can > be clearer about that specific point, and also I believe there's a > copy/paste error there in the Cross-referencing section > <https://sphinx-click.readthedocs.io/en/latest/usage/#cross-referencing> > where it says: > Specifically, it uses the program > <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-program> > , program > <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-option>, > and program > <https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-envvar> > directives. > > Thanks again for your help, > Tomer. > > [image: Screenshot from 2022-04-06 16-34-49.png] > > > On Monday, April 4, 2022 at 7:15:45 PM UTC+3 Stephen Finucane wrote: > >> On Mon, 2022-04-04 at 06:38 -0700, Tomer wrote: >> > Hi Stephen, >> > Thank you for taking the time to reply. >> > >> > I was aware that this was a Sphinx group, but I didn't find anywhere >> better to >> > ask, and I thought that if someone at least knew how I could read the >> .doctree >> > files that would also help, and that does sound relevant to this group. >> > I also thought I might luck out and find someone who knows about >> sphinx-click >> > specifically, so I'm glad that worked out. =) >> > Since I had a question rather than an actual issue I didn't think the >> issue >> > tracker was the right place for it. Is that normally an acceptable >> place for >> > general questions? >> >> It depends on the project but I'm happy for you to do that, personally. I >> suspect you'll be told if something is not considered appropriate. >> >> > Regarding your answer: >> > I did see that in the documentation, but I didn't know that the >> commands and >> > groups were considered "programs." >> >> Yeah, this is Sphinx terminology. We're just borrowing directives and >> roles from >> the standard domain [1]. Each subcommand is considered a separate program >> in >> Sphinx lingo. >> >> > I misunderstood that to only refer to the top level of the Click >> application >> > and thought that the documentation merely didn't specify anything about >> groups >> > and commands in general. >> > I'm very new to Sphinx so unfortunately not yet well versed in its >> > terminology. >> >> If you think that the documentation could be clarified then by all means, >> I'd >> happily accept PRs for this too (even WIP PRs - I can finish them up >> myself). >> >> > Having those custom anchors would be very nice for sure. >> > I don't know if I'll have the time to get into this to actually >> implement it >> > myself but I'll tell you if I do (or open an issue and say it there). >> >> No worries. I'm unlikely to have time myself to draft this entirely but >> I'd be >> happy to drag something over the line if you or someone else proposed a >> solid >> WIP PR at some point. >> >> > Thank you for maintaining the project - it's most definitely very >> useful! >> > Since I managed to reach you here, I hope you don't mind if I ask a >> couple of >> > more questions. =P >> > >> > I'd like to generate documentation for a CLI tool with multiple command >> > groups, which would show quite a bit of information. >> > To this end I'd like to split it into separate pages - similar to how >> the >> > Click --help display works, where it shows you short help text for the >> groups >> > if you run it without any other arguments, and then shows things >> specific to a >> > group if you run it with "group --help". >> > I haven't found a built-in way to do this, so my current solution is to >> > generate an .rst page for each group and put a ".. click::" directive >> there. >> > Not ideal, but should work. If you have a better suggestion I'd love to >> know. >> >> This is how I'd do this also. Again, it's possible that sphinx-click >> could >> autogenerate these pages for you in a similar vein to how Sphinx's >> sphinx-apidoc >> tool will generate .rst pages containing 'autodoc' directives [2], but it >> doesn't currently do this. Another option is to enable nested >> documentation >> generation (using the 'nested' argument), but this would put everything >> on a >> single page. You seem to have already explored this. >> >> > However, I don't know what to do in order to display a short summary of >> the >> > commands for each group. >> > Ideally I'd like to put three of these directives one after the other, >> with >> > their :nested: options set to none, short and full respectively. Doing >> this >> > actually works somewhat decently, but some of the information repeats >> itself >> > (namely the contents of the none form shows up in all of them). >> > Is there a way to make the directive not list the program name and >> > description? >> >> Not at this time, no. It's very much an all or nothing thing. I hadn't >> really >> envisioned further customization than what the existing arguments >> ('prog', >> 'nested', 'commands') allows. >> >> > Another thing I'd like to do is be able to have the titles of the >> commands in >> > the short form reference their anchors. Even if it's done manually in >> the form >> > of entering a link to the HTML page and section, that would still be >> nice to >> > have. >> > Is there a way to modify the output of that directive? >> >> Again, modification of the output isn't currently possible beyond what >> those >> three options allow for. It would probably be useful to open an issue >> with >> screenshots of what you're trying to achieve (and why) so we can see >> whether >> this is worth doing. >> >> > >> > Thanks again, >> > Tomer. >> >> Hope this helps, >> Stephen >> >> [1] >> https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#the-standard-domain >> [2] https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html >> >> > On Monday, April 4, 2022 at 2:57:40 PM UTC+3 Stephen Finucane wrote: >> > > 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/f1df6215-9eb3-4b01-aa57-d31339995c9dn%40googlegroups.com > <https://groups.google.com/d/msgid/sphinx-users/f1df6215-9eb3-4b01-aa57-d31339995c9dn%40googlegroups.com?utm_medium=email&utm_source=footer> > . > -- 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/CAFw_2YrvhgMqnNV%2BtWeFvB92iD78OeL93J_icQwB3qyaKnHXoQ%40mail.gmail.com.
