Add bundle_info.xml tag for documentation file locations

[Conrad Huang]

Instead of enforcing a particular directory structure for documentation in bundles (currently docs/{user,devel,tools,etc}, let developers specify the documentation file locations in bundle_info.xml. If none is provided, fall back to the current scheme.

[Eric Pettersen]

It would also be useful if, as part of this change, it were possible to specify that certain tools should not be included in the tools index. Most typically useful for simple, "obvious", tools like Show Volume Menu and Show Sequence Viewer.

[Greg Couch]

In the Show Volume Menu case, is there an alternative? It acts like a preference, and is sticky across invocations of ChimeraX. I'm not a fan of menus appearing and disappearing. I'd rather have the menu entries grayed-out if they're not applicable.

[Eric Pettersen]

I don't think anyone wants a _top level_ greyed-out menu. That would just be weird and mystifying -- and added clutter to users that don't use volume data.

[goddard@…]

The Volume menu is just an optional menu.  It could have a configuration setting.  The Show Volume Menu in Tools / Volume Data is just a convenient way for people to discover this option.  That menu entry sets the currently hidden configuration settings, so future sessions will show the top level Volume menu too.

[Greg Couch]

Won't make 1.3.

[Greg Couch]

Not going to make 1.5 unfortunately.

[Tom Goddard]

Ticket retargeted after milestone closed

[Zach Pearson]

I would advocate against this and in favor of standardization.

[Eric Pettersen]

Maybe we should de-milestone this and wait for it to become an issue in practice? If wheel files supported symbolic links then this issue would be completely moot, but AFAICT wheel files do not support symbolic links.

[Zach Pearson]

Isn't this kind of superseded by extra-files? You can have your docs in any tree you want them to be in as long as you direct them to src/docs right?

[Eric Pettersen]

What does "direct them to src/docs" mean exactly?

[Zach Pearson]

It's where we imply users should put documentation in tutorials ​such as the Qt Tool tutorial. In that tutorial, the sample files section puts documentation under src/docs/user/commands

[Eric Pettersen]

If a tool has a "help" attribute whose value is "help:user/tools/mytool.html" then the help system automatically looks in the bundle's "docs" subdirectory for it. Maybe I'm missing something, but you can't have the actual documentation live in some other tree since wheels do not support symbolic links.

[Zach Pearson]

I mean that with extra-files you can have them anywhere you want and they'll be bundled in the correct location if you set the target destination correctly. extra-files copies the files into your wheel.

[Eric Pettersen]

Well, probably ExtraDir rather than ExtraFile, but I see what you mean. Now I recommend just closing this ticket until some kind of actual problematic use case shows up.

[Greg Couch]

The help code effectively does a virtual filesystem overlay to find a bundle's documentation. So it requires that user documentation be in docs/user/{commands,tools}/ in the provided package.

I believe this ticket was a request to support, in bundle_info.xml, a way to eliminate one or two levels of that documentation directory hierarchy in the bundle's source. If the ExtraFiles mechanism can do already do that, then it just needs to be documented.

[Eric Pettersen]

No ExtraDir does not eliminate the hierarchy requirement. But the work to implement this does not seem worth the minor upside. At the very least, this ticket should not be milestoned.

[Tristan Croll]

No problem here (I see I added myself as cc to the ticket way back, but
this stopped being an issue for me years ago). For what it’s worth, I keep
my Sphinx source files in a separate tree, then just have it build the
completed html into the correct directory in the source tree. Apart from
the annoying need to do “make app-install; make docs; make app-install” to
populate the API documentation (a Sphinx evil, not specific to ChimeraX) it
works fine.

On Wed, 18 Sep 2024 at 21:52, ChimeraX <ChimeraX-bugs-admin@cgl.ucsf.edu>
wrote:

>
>

[Zach Pearson]

I'll write the documentation

[Zach Pearson]

I've added the following clause to writing_bundles.rst:

Bundle Documentation
--------------------

Your bundle's documentation can be found and shown by ChimeraX's
help tool. The help tool will look for documentation in
``docs/user/commands`` or ``docs/user/tools``. 

You can store your documentation in your bundle's ``src`` tree, or
next to it as long as you use the appropriate ``ExtraDir`` (XML)
attributes to package them in the correct locations: ::

  src/docs/user/commands/
  src/docs/user/tools/

For example, if your bundle had these folders: ::

  src docs/user/commands docs/user/tools

Then you would put the following in your ``bundle_info.xml`` ::

  <ExtraFiles>
    <ExtraDir source='docs'/>
  </ExtraFiles>

If you use ``pyproject.toml``, you can put your documentation in
any tree structure you like. For example, if your folder structure
was ::

  src docs/commands docs/tools

Then your TOML would include: ::

  [chimerax.extra-files]
  "src/docs/user/commands" = ["docs/commands/*"]
  "src/docs/user/tools" = ["docs/tools/*"]

[Greg Couch]

The documentation update is the fix. The files need to be installed in the right location, but the source does not need to match.