Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

consider publishing docs in GitHub pages #663

Closed
prjemian opened this issue May 13, 2019 · 15 comments
Closed

consider publishing docs in GitHub pages #663

prjemian opened this issue May 13, 2019 · 15 comments
Assignees
Labels
Milestone

Comments

@prjemian
Copy link
Contributor

@prjemian prjemian commented May 13, 2019

For more timely updates to the documentation, consider publishing directly from travis-ci to GitHub pages. We are motivated by repeated permissions failures on our jenkins server resulting in failure to post documentation revisions. Other projects hosted on GH do this already.

@prjemian prjemian added this to the NXDL 2019.3 milestone May 13, 2019
@prjemian prjemian self-assigned this May 13, 2019
@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented May 13, 2019

@danielballan : You've just been updating how bluesky posts its documentation to GH Pages. Can you show us how or point us in the right direction?

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented May 14, 2019

First, branch this repo with name gh-pages

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented May 14, 2019

Check the GitHub Pages settings here

@prjemian

This comment has been minimized.

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented May 15, 2019

Publish to GitHub Pages from local build

Following this blog with additional help and more help. Also, have just built the documentation in the development directory (~/Documents/eclipse/NeXus/definitions) using make local.

Basic Procedure

  1. cd ~/Documents
  2. mkdir gh-pages (separate directory from usual code development)
  3. git clone https://github.com/nexusformat/definitions
  4. cd definitions
  5. git checkout --orphan gh-pages
  6. git rm -rf . (clear out all existing content, all but the .git directory)
  7. pushd ~/Documents/eclipse/NeXus/definitions/build/manual/build/html
  8. tar cf - * .nojekyll | (cd ~/Documents/gh-pages/definitions && tar xf -)
  9. popd
  10. git add .
  11. git commit -m publish
  12. git push -u origin gh-pages
  13. view content: https://nexusformat.github.io/definitions
@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented May 15, 2019

Now that the gh-pages branch exists, describe how to post updated docs. Then, automate this from travis-ci.

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented May 15, 2019

Update with new content

... working from the same directory as above ...

... assume that documentation has just been rebuilt ...

  1. git branch (confirmwe are on the gh-pages publishing branch -- do not do this to master!)
  2. git rm -rf .
  3. copy in the complete html content as above
  4. git add .
  5. git commit -m publish
  6. git push -u origin gh-pages
@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented Jul 14, 2019

@danielballan

This comment has been minimized.

Copy link

@danielballan danielballan commented Jul 14, 2019

Somehow I missed being tagged on this back in May. I recommend the approach that I documented here: https://nsls-ii.github.io/scientific-python-cookiecutter/publishing-docs.html

I’ve tried a couple approaches over the years and this one has been the easiest to set up and keep working.

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented Jul 14, 2019

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented Nov 9, 2019

@FreddieAkeroyd emailed (to nexus-committee@nexusformat.org):

There was discussion about some of our web links not being https at the telco. Some links refer to http://download.nexusformat.org/ which is an isis server and which currently does not have a valid certificate for download.nexusformat.org (so https will work, but the browser will moan at you). The user manual is built on the ISIS Jenkins server at the same location and then published to download.nexusformat.org I can get a valid certificate for this address and we update links to https, or we could look at publishing the manual (and other stuff) elsewhere. We could push the built user manual html files to github pages maybe? I’m not sure what else on download.nexusformat.org is still relevant these days

@prjemian

This comment has been minimized.

Copy link
Contributor Author

@prjemian prjemian commented Jan 21, 2020

2020 Code Camp assesses this might too long to resolve but we can make technical comments on how to implement this. We should also consider using https distribution.

@FreddieAkeroyd

This comment has been minimized.

Copy link
Member

@FreddieAkeroyd FreddieAkeroyd commented Jan 22, 2020

Above PR publishes docs to gh-pages using current Jenkins build system

@FreddieAkeroyd

This comment has been minimized.

Copy link
Member

@FreddieAkeroyd FreddieAkeroyd commented Jan 23, 2020

Now publishing to gh pages, redirect in place on old server, PR on main nexus wiki to update links there nexusformat/wiki#4

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.