Need merged view of help documentation

[Greg Couch]

With documentation moving to the bundle that implements the functionality, it becomes impossible to check that links within the documentation work. So add a make target that generates a merged version of the documentation -- complete with the generated index.

[Greg Couch]

Use vdoc directory to mirror urls. All files will be symbolic links. Warn about conflicts. Have a build target to rebuild virtual documentation directory. Have check target to confirm that symlinks were not accidentally replaced with a real file.

[Conrad Huang]

First step implemented in 8e1f1e5d0. New top level directory, vdocs, has make targets:

• build (aliases all and install): create symlinks to files in ../docs/user and ../src/bundles/*/src/docs to create file hierarchy where relative URLs such as users/tools/viewdockx.html should work properly
• check: verify that entries in hierarchy are either directories or symlinks. Real files should not be present in the virtual documentation tree.
• distclean: remove symlinks and directories created by build.
• clean: clean if check is clean.

The intended usage is:

cd vdocs
make build

which creates a single tree with symlinks to all (currently user) documentation files.

Caveats for vdocs:

• Documentation files in source of bundles (../src/bundles/*/src/docs) appear in the same hierarchy as main documentation (../docs.
• File name clashes are reported during make build. File name clashes may occur if multiple bundles use the same file name in their documentation. It is probably best if we can avoid that, even though the correct file will be used by ChimeraX browser.
• You can update file contents (edit files pointed to by symlinks) in vdocs but cannot replace the entire file with another or add new files. The "true" location of documentation files are still either in main documentation (e.g., tutorials and legacy files) or bundle source trees (e.g., viewdockx). Any new file must be added to their "true" location and then make build rerun to create the corresponding symlink in vdocs.
• On Windows, you need to run as administrator to execute make build and the resulting tree still has permission issues. Since the intended use for vdocs is on Linux (plato) or Mac (chopin), this may not be an issue.

Question: is this at all useful in general, and, more specifically, for Elaine?

[pett]

When you say there may be file-name clashes, so there's no "bundle name" folder level in the virtual documentation?

--Eric

[Elaine Meng]

There’s at least one case where the command help filename is same as tool help filename. Is that a problem?

[Conrad Huang]

There is no bundle name in the URL scheme, so there is no bundle name in the virtual documentation tree. For example, command documentation for viewdockx is user/commands/viewdockx.html, so the vdocs location for the file is vdocs/user/commands/viewdockx.html.

There command and tool documentation files have URLs with commands and tools in them (i.e., user/commands/viewdockx.html and user/tools/viewdockx.html, so they will not clash in vdocs. For example, both vdocs/user/commands/viewdockx.html and vdocs/user/tools/viewdockx.html should be created (as soon as I fix the bug I just found).

[Conrad Huang]

Script was using the wrong source for symlinks. Fixed in cb4569e72. This also fixes the "permission issues" in the generated vdocs tree on Windows (but you still need to run as administrator to run make build).

The corrected script also complained:

user\tools\Toolbar.html: already exists and links to ..\..\..\docs\user\tools\toolbar.html, not ..\..\..\src\bundles\toolbar\src\docs\user\tools\Toolbar.html

Both chimerax/docs\user\tools\toolbar.html and chimerax/src\bundles\toolbar\src\docs\user\tools\Toolbar.html exist. Their URLs are different, since URLs are case sensitive. However, Windows thinks that their file names are the same because the Windows file system is case insensitive. Extrapolating, this situation will also be a problem on Mac but not on Linux. What should we do?

[Elaine Meng]

I have no idea where the second one came from.  It appears to have hardly anything in it, and I don’t think I made it even though it has my standard header and footer for User Guide pages, with broken link to ChiX documentation icon … the words don’t sound like something I would write (Greg…. ?).  if I did make it, it was definitely by mistake, and as far as I’m concerned we could just delete it.  

Elaine

[Greg Couch]

Make it so vdocs can built using the chimerax-daily build to generate the index.html file. Do a "make from-daily" in the vdocs directory. This is so Elaine can preview the current documentation on plato without have to build the ChimeraX application.

[Elaine Meng]

I haven’t checked comprehensively but at least a few links are still broken in the vdocs.  For example the “Quick Start Guide” and “cxlinks.js” links in this page in my vdocs preview:

http://www.cgl.ucsf.edu/home/meng/chimerax/vdocs/user/tools/helpviewer.html

They’re still OK in my original preview (non-vdocs)

http://www.cgl.ucsf.edu/home/meng/chimerax/docs/user/tools/helpviewer.html