Re: motor6-10

[Matt Newville <newville@cars.uchicago.edu>]

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 <rivers@cars.uchicago.edu> 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: tech-talk-bounces@aps.anl.gov [tech-talk-bounces@aps.anl.gov] on behalf of Benjamin Franksen [benjamin.franksen@helmholtz-berlin.de]
Sent: Wednesday, November 09, 2016 5:21 AM
To: tech-talk@aps.anl.gov
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