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!
--
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/68beee0451d46beef4e39e95d932a963df7e1e60.camel%40that.guru.
