Experimental Physics and
Industrial Control System

Michael Davidsaver <[email protected]> · Wed, 9 Nov 2016 09:44:57 -0500

An example: http://mdavidsaver.github.io/epics-doc/

I found it annoying to manually switch branches, or have a separate
checkout, to move generated documentation to a gh-pages branch.  So I
automated this process.  See Makefile and commit-gh.sh in
https://github.com/mdavidsaver/epics-doc

I've also been intending to look into the recently added git worktree
feature (git >=2.5) as it seems to provide a less nuts and bolts
alternative to accomplish this.  https://git-scm.com/docs/git-worktree

On 11/09/2016 07:44 AM, Matt Newville wrote:
> I think this may not have been mentioned in this thread:
> 
> An easy way to have HTML-rendered docs for a github repository is to
> make a branch called "gh-pages" and put the HTML docs there. For
> example, if epics-modules/motor had a gh-pages, this would get published to
>      http://epics-modules.github.io/motor
> 
> with the docs automatically updated every time a push is made to the
> gh-pages branch.   More details are at
>     https://help.github.com/categories/github-pages-basics/
> 
> --Matt
> 
> On Wed, Nov 9, 2016 at 6:24 AM, Mark Rivers <[email protected]
> <mailto:[email protected]>> wrote:
> 
>     > Try
>     >
>     https://rawgit.com/epics-modules/autosave/master/documentation/autoSaveRestore.html
>     <https://rawgit.com/epics-modules/autosave/master/documentation/autoSaveRestore.html>
> 
>     > You can put this URL as a link into a top-level README.md.Can I
>     use a rawgit.com <http://rawgit.com> development URL on > a
>     production website or in public example code?
> 
>     This is from the FAQ for rawgit:
> 
>     **************************************
>     Can I use a rawgit.com <http://rawgit.com> development URL on a
>     production website or in public example code?
> 
>     No. Only use rawgit.com <http://rawgit.com> URLs for low-traffic
>     testing or for sharing temporary demos with a few people during
>     development. Please use cdn.rawgit.com <http://cdn.rawgit.com> for
>     anything that might result in heavy traffic or that people might
>     copy and paste into their own code.
> 
>     Please don't use rawgit.com <http://rawgit.com> URLs in example code
>     or in public demos, because people often copy and paste that code
>     and use it in production apps without realizing that they need to
>     change the RawGit URLs. Then they send too much traffic to RawGit,
>     get throttled, and their apps break.
> 
>     When people misuse rawgit.com <http://rawgit.com> development URLs,
>     it costs me money. Please be considerate.
> 
>     Remember, only use cdn.rawgit.com <http://cdn.rawgit.com> in production.
> 
>     How long does the CDN cache files? How can I make it refresh my file?
> 
>     The CDN caches files permanently based on their path. It ignores
>     query strings. This is done to improve performance and to make it
>     possible for the CDN to handle massive amounts of traffic without
>     causing excessive load on RawGit or GitHub's servers.
> 
>     To ensure that the CDN always serves the version of the file you
>     want, use a git tag or commit hash in the file's path instead of a
>     branch name, and update the URL if you push a new version of the file.
> 
>     So, instead of a URL like
>     https://cdn.rawgit.com/user/repo/branch/file
>     <https://cdn.rawgit.com/user/repo/branch/file>, use a URL like
>     https://cdn.rawgit.com/user/repo/tag/file
>     <https://cdn.rawgit.com/user/repo/tag/file> or
>     https://cdn.rawgit.com/user/repo/commit/file
>     <https://cdn.rawgit.com/user/repo/commit/file>.
>     **************************************
> 
>     So, rawgit policy explicitly says that rawgit.com
>     <http://rawgit.com> URLs must not be put in production websites. 
>     cdn.rawgit.com <http://cdn.rawgit.com> must be used instead, because
>     it does permanent caching.  But then you must put the git tag or
>     commit in the URL, which is less convenient.
> 
>     Mark
> 
> 
>     ________________________________________
>     From: [email protected]
>     <mailto:[email protected]>
>     [[email protected]
>     <mailto:[email protected]>] on behalf of Benjamin
>     Franksen [[email protected]
>     <mailto:[email protected]>]
>     Sent: Wednesday, November 09, 2016 5:21 AM
>     To: [email protected] <mailto:[email protected]>
>     Subject: Re: motor6-10
> 
>     On 07.11.2016 19:29, Mooney, Tim M. wrote:
>     > I think it's a good idea to maintain links at
>     http://aps.anl.gov/bcda/synApps <http://aps.anl.gov/bcda/synApps>
>     for module releases and
>     > documentation, because a lot of already released documentation (by
>     us and by other people) has
>     > hardcoded links to that URL.  Also, I don't know how automatically
>     to have .html files hosted on github
>     > display as intended; github displays them as text files, which is
>     ok for development, but not helpful for
>     > folks who just want to read the documentation.  (For clarity, go
>     to http://aps.anl.gov/bcda/synApps/autosave
>     <http://aps.anl.gov/bcda/synApps/autosave>
>     > /autosave.html, and click on a recent link to
>     'autosaveRestore.html.'  You get interpreted HTML, via
>     > htmlpreview.github.io <http://htmlpreview.github.io>.  If you go
>     to github -
>     >
>     https://github.com/epics-modules/autosave/blob/master/documentation/autoSaveRestore.html
>     <https://github.com/epics-modules/autosave/blob/master/documentation/autoSaveRestore.html>
>     -
>     > you get the same thing as a text file, which is not what most
>     people want.)
> 
>     Try
>     https://rawgit.com/epics-modules/autosave/master/documentation/autoSaveRestore.html
>     <https://rawgit.com/epics-modules/autosave/master/documentation/autoSaveRestore.html>
> 
>     You can put this URL as a link into a top-level README.md.
> 
>     Cheers
>     Ben
>     --
>     "Make it so they have to reboot after every typo." ― Scott Adams
> 
> 

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System