ISOLDE synopsis in User Guide Index should link to ISOLDE website

[Elaine Meng]

Hi Tristan,
ChimeraX tools automatically (through some magic from Greg and Conrad) get listed in the User Guide index that is shown with menu: Help... User Guide. This magic is not yet applied to any documentation on our website, so this is only for what is included in the downloaded copy.

ISOLDE is listed, at least if installed, but without any link to your website. Since you have so much nice documentation, it would be nice if there were such a link. Also currently its synopsis says it is iMDFF, which may no longer be how you want it described these days. Greg tells me that in this downloaded User Guide index:

(1) for automatically added entries, the name is hyperlinked to the installed documentation if any is found. The bundle should be providing that documentation. (However, yours is on your website, which is also fine, more on this below...)
(2) the text after the dash is from the Synopsis section of the bundle's bundle_info.xml file.

I can manually add entries into the index HTML, which would override any of these automated approaches. Thus there are at least two ways to get the link to your website in this index. Which of these do you prefer?

(A) you update the Synopsis section of the bundle's bundle_info.xml file to say whatever you like, somehow including the link to your website.
(B) I manually add an entry to the index HTML, with link to ISOLDE website. The downside of this option is that it would then always show up in the index even if the user has not installed ISOLDE.

[Tristan Croll]

Hi Elaine,

I do actually include ISOLDE’s documentation in the bundle (in {bundle root}/docs/isolde). If you can tell me how to tell ChimeraX where to find it, I’ll get it sorted.
 
 
- Tristan
 

 

[Elaine Meng]

I don’t know the details, so Greg will have to fill you in (Greg?  thanks in advance)

[Greg Couch]

Documentation is looked for in the docs subdirectory for the bundle's main package. For example, see the viewdockx bundle. In its bundle_info.xml:

<DataFiles>
  <DataDir>docs</DataDir>
</DataFiles>

And there is src/docs/user/tools/viewdockx.html -- the name of the file should match the name of the tool in bundle_info.xml with the same capitalization and spaces are replaced with underscores.

And there is src/docs/users/commands/viewdockx.html -- the name of the file should match the name of the command in bundle_info.xml. Only the first word of a multiword command is linked to.

[Tristan Croll]

Ok, should be able to make that work. ISOLDE’s docs currently start at src/docs/isolde/index.html... sounds like it’ll just be some fairly trivial rearrangement, plus some new files specific to commands.
 

 

[Tristan Croll]

This layout isn't really ideal for documentation generated using Sphinx 
- it expects to have a top-level document (default name "index.html", 
but that can be changed) that the rest of the documentation tree is 
subordinate to. Will it break anything if I have a file 
"src/docs/user/isolde.html" (which would act as the entry point for 
people clicking ISOLDE's Help button, linking to GUI, command and API 
documentation)?

On 2019-10-21 21:07, ChimeraX wrote:

[Elaine Meng]

The scheme for linking into the User Guide is only for  the user documentation.  API stuff and programmer documentation are handled separately.  The bundle example(s) from Conrad may have information on how that’s handled, but Greg and Conrad would know the details.

[Tristan Croll]

At the moment *all* my documentation is defined as RestructuredText and built by Sphinx. It *seems* to behave OK if I build it as:

user
 |_ isolde.html
 |_tools
    |_isolde.html
    |_(other ISOLDE docs)
 |_commands
    |_isolde.html

 

 

[Tristan Croll]

In today's ChimeraX build, the isolde link under "Commands" works 
(although what it links to is still just a stub - working on that). The 
one under "Tools" doesn't (i.e. it isn't a link), but typing the address 
"help:user/tools/isolde.html" shows the correct page.

On 2019-10-25 16:00, ChimeraX wrote:

[Greg Couch]

Capitalization matters. The tool name is ISOLDE, so the file should be ISOLDE.html, not isolde.html. It's not yet an issue with ViewDockX because there is an explicit link in the list of tools.

[Tristan Croll]

Ah! The lowercase viewdockx.html is what threw me.
 

 

[Tristan Croll]

Also, alongside these I have a user/isolde.html, user/tutorials/isolde.html and user/api/isolde.html. They don’t seem to be causing any trouble - let me know if they will.
 

 

[Greg Couch]

Only the tool and command are automatically extended at this time.

[Tristan Croll]

Working now. Excellent! Will be in my next release.

[Tristan Croll]

Related question: how should I go about documenting Clipper's addition 
to the "open" command for structure factors (e.g. open xxx.mtz 
structureModel #1)?

On 2019-11-08 11:08, ChimeraX wrote:

[Elaine Meng]

I don’t think we have any nice (i.e. automatic) way to fold in changes to documentation for an otherwise existing command or tool.  I’ve only dealt with this so far for the Maestro bundle for reading Maestro format (docking output from Glide).  In the ViewDockX documentation, I list possible input formats, including Maestro along with a description that to read it, one must get the Maestro bundle on the Toolshed.

I could add something similar to the table of formats in the “open” command documentation, but in that case it should follow the general scheme of the existing formats in having known suffix as well as ability to use “format blah”  (e.g. “format mtz”) in the command.  Details should probably be in the documentation for Clipper bundle, however, maybe at the Toolshed website.

Is the mtz file type registered?  I installed clipper but I didn’t see the format listed by the “open formats” command. The list is long, maybe I just failed to see it.

[Tristan Croll]

Yes, it's there (fifth from the bottom of the table for me):

Crystallographic reflection file	mtz	.mtz

Clipper can also open structure factor .cif files (the format they're 
provided in by the PDB) but since there's no easy way to disambiguate 
these from mmCIF that's only implemented under the "clipper open" 
command.

On 2019-11-12 21:28, ChimeraX wrote:

[Tristan Croll]

Just noticed a bug related to this in the help system. If I go to the help via Help/User Guide in the menu, then the Tool and command help links are there as expected. But if I type "help" in the command line and then click the link to "ChimeraX User Guide" they're missing.

[Greg Couch]

I'll fix the help index generation.

[Greg Couch]

Fixed getting generated user manual index with accessing via a href. Fixes links from bundle documentation to rest of documentation.