Experimental Physics and
Industrial Control System

Pete Jemian <[email protected]> · Wed, 9 Nov 2016 14:29:03 -0600

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.

Pete

On 11/9/2016 6:42 AM, Pete Jemian wrote:

This SO page describes the method:

http://stackoverflow.com/questions/8446218/how-to-see-an-html-page-on-github-as-a-normal-rendered-html-page-to-see-preview

The selected answer on that page is:

The most comfortable way to preview HTML files on GitHub is to go to
http://htmlpreview.github.com/ or just prepend it to the original URL,
i.e.:
http://htmlpreview.github.com/?https://github.com/bartaz/impress.js/blob/master/index.html

On 11/9/2016 6:24 AM, Mark Rivers wrote:

Try
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 development URL on > a production website or in public
example code?

This is from the FAQ for rawgit:

**************************************
Can I use a rawgit.com development URL on a production website or in
public example code?

No. Only use rawgit.com URLs for low-traffic testing or for sharing
temporary demos with a few people during development. Please use
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 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 development URLs, it costs me money.
Please be considerate.

Remember, only use 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, use a URL like
https://cdn.rawgit.com/user/repo/tag/file or
https://cdn.rawgit.com/user/repo/commit/file.
**************************************

So, rawgit policy explicitly says that rawgit.com URLs must not be put
in production websites.  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] [[email protected]] on
behalf of Benjamin Franksen [[email protected]]
Sent: Wednesday, November 09, 2016 5:21 AM
To: [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 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
/autosave.html, and click on a recent link to
'autosaveRestore.html.'  You get interpreted HTML, via
htmlpreview.github.io.  If you go to github -
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

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

--
----------------------------------------------------------
Pete R. Jemian, Ph.D.                <[email protected]>
Beam line Controls and Data Acquisition, Group Leader
Advanced Photon Source,   Argonne National Laboratory
Argonne, IL  60439                   630 - 252 - 3189
-----------------------------------------------------------
   Education is the one thing for which people
      are willing to pay yet not receive.
-----------------------------------------------------------

Experimental Physics and Industrial Control System

Experimental Physics and
Industrial Control System