On Wed, 2022-04-06 at 07:14 -0700, Tomer 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.
These all sound reasonable. I'd be happy to review a PR with these. It doesn't need to be initially complete, assuming you'd like feedback before investing time into writing tests. > * 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. :nested: fuller ? > 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. This sounds helpful, though it's tough to say how useful it would be without seeing the code. Feel free to submit a WIP pull request for review. Try to keep it separate from the other items above so we can review it in isolation. As an aside, the typical way people seem to want to do this is using the form feed (\f) character to hide Sphinx-specific stuff from click output. You need a recent version of click to support this but it otherwise seems like a good call. More information at https://github.com/click-contrib/sphinx-click/issues/56 Another option would be to write a plugin for click that would transform help texts and remove the Sphinx-specific stuff using something like https://pypi.org/project/rst2txt/. This would definitely be more difficult but it's not impossible. > > 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 where it says: > Specifically, it uses the program, program, and program directives. Good spot. Fixed. Hope this helps, Stephen > > Thanks again for your help, > Tomer. > > 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 > . -- 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/ea9ba5fd05e7563fc0370294bc4138bd1a71709a.camel%40that.guru.
