RE: motor6-10

[Mark Rivers <rivers@cars.uchicago.edu>]

One concern I have with moving the home of the synApps documentation from the APS to github is the existence of many URL references in existing documentation.  Here is a search of the synApps (and areaDetector) tree for such links to documents at the APS:

 

corvette:~/devel>find . -name '*.html' -exec grep -H www.aps.anl.gov {} \; | wc

    469    2174   66753

 

So there are 469 such links that need to be changed.  Since the “best” URL to use for git documentation seems to be a moving target, I worry about having to change these frequently.

 

There are also 339 references to the documentation on the CARS web server for software I have developed:

 

corvette:~/devel>find . -name '*.html' -exec grep -H "http://cars" {} \; | wc

    339    1325   49981

 

In areaDetector there are many cross-links to documentation within the different areaDetector repositories.  I have avoided putting URLs on those at all, and simply copy all of the HTML files to the same directory on our Web server, so the files will be found automatically.  For example:

 

./areaDetector-2-5/documentation/html/simDetectorDoc.html:    This is an <a href="" <a href="">

 

So the EPICS documentation link uses an http URL, but areaDetector.html is assumed to be a file in the same directory.  How would this be handled in a maintainable way if the documentation home move to github where simDetector.html and areaDetector.html reside in different repositories?

 

Mark

 

 

 

 

 

From: tech-talk-bounces@aps.anl.gov [mailto:tech-talk-bounces@aps.anl.gov] On Behalf Of Matt Newville
Sent: Wednesday, November 09, 2016 4:06 PM
To: Pete Jemian
Cc: EPICS Tech Talk
Subject: Re: motor6-10

 

Pete,

 

On Wed, Nov 9, 2016 at 2:29 PM, Pete Jemian <jemian@anl.gov> wrote:

See the synApps utils module for an example:

https://github.com/EPICS-synApps/utils#html-documentation

I will apply this method to the other synApps modules.
It looks easier to maintain than publishing through gh-pages and keeps the HTML documentation in the master branch without need for the occasional merge to a gh-pages branch.

 

Oh, one can set up gh-pages to use the docs/ folder in the master branch (or even just the master branch) instead of a separate gh-pages branch.

I believe the separate branch was the only option for a while. Many of us still prefer this when the HTML docs are output compiled from the document source files (say RST/Sphinx or doxygen). In these cases, the master branch could have the document source files, but not the rendered result, which makes for cleaner and more meaningful diffs in the master branch when the docs are rebuilt.

As Michael suggested, a few scripts and/or a Makefile for "publish the docs" can make using gh-pages very easy.