This is an RFC for an enhancement in JSS upstream.
I'd like to take the javadoc that's output as part of the build process and push it to either the gh_pages or create a docs/ folder on master.
gh_pages
docs/
This would allow users of JSS to quickly see the javadoc online, similar to what many other projects host:
I probably would not version them (like e.g., Google Guava does) and instead base them off of the code in master (perhaps look into using Travis to update them nightly), and would not maintain them for previous versions of JSS.
master
For more information, see the GitHub documentation on the subject of GitHub Pages hosting:
Here is the current javadocs:
jss
If people are in favor, I'll create a new branch upstream from the gh-pages branch in my jss-javadoc repository.
gh-pages
jss-javadoc
Benefits:
Downsides:
Thoughts?
/cc: @mharmsen, @cfu, @jmagne, @edewata, @dmoluguw, @emaldonado
Great idea, let's do it. gh-pages is a great idea, even better if we can somehow use Travis or other system to do it automatically.
Along these lines, here is a handy script I use (defined as git snapshot alias in my .gitconfig) to automatically commit the contents of a subdirectory (e.g. docs/) to some other branch (e.g. gh-pages) that isn't checked out. It might be useful here. https://github.com/frasertweedale/dotfiles/blob/1f2300c90d5e8b472f550495e367a4dc684669c4/.gitconfig#L91-L103. Usage is e.g. git snapshot docs/ gh-pages.
git snapshot
.gitconfig
git snapshot docs/ gh-pages
Metadata Update from @ftweedal: - Custom field component adjusted to None - Custom field feature adjusted to None - Custom field origin adjusted to None - Custom field proposedmilestone adjusted to None - Custom field proposedpriority adjusted to None - Custom field reviewer adjusted to None - Custom field type adjusted to None - Custom field version adjusted to None
@ftweedal Thanks! I think for sanity's sake, it'd be nice to make gh-pages a regular branch (sans code) and then create a new user in GitHub for Travis-based automation. This new user wouldn't be given commit access and instead would use the API to open a new pull request. This PR can then be reviewed / closed / etc.
We could probably go a step further and detect when we have an open PR, close that one, and open a new one instead if it hasn't been merged. This could be a nightly or weekly task in Travis. Because it never gets commit access, it would be a smaller security risk if credentials get exposed, etc.
That way too, if we wish to push other documentation or other pages to gh-pages, we can and either do it automatically in this script or do it manually without risk of Travis overwriting it without us knowing.
I'm leaning now towards gh-pages branch over docs/ folder on master... if we add generated HTML javadocs to docs/ folder on master, users get the same information by typing build_java.pl javadoc in the source repository, so it seems redundant. They get the same content when they clone, but the gh-pages branch wouldn't necessarily be visible.
build_java.pl javadoc
Hey @cipherboy, I agree that we don't want to commit compiled doc artifacts into master, and should rather put them in gh-pages branch or wherever. In previous comment I demonstrated how, if we have master checked out and build the docs, which (for sake of argument) end up in docs/ subdir, then we can snapshot the contents of that subdir onto the gh-pages branch, without actually having to switch branches.
Please see my lca2018 lightning talk for demo. https://www.youtube.com/watch?v=3MDsu6iFAD0&feature=youtu.be&t=2360 :)
@ftweedal Ah sorry -- I think I understand now (and stepped through it this time). That's kinda nifty, I do admit. Thanks for that :-)
I've updated the description above with the following example:
Here is the current javadocs: - https://github.com/cipherboy/jss-javadoc/tree/gh-pages -- Source contents. - https://cipherboy.github.io/jss-javadoc/ -- Live view as it would appear on jss (except URL would be https://dogtagpki.github.io/jss/) - https://github.com/cipherboy/dotfiles/blob/master/bashrc.d/jss.bash -- script for updating
I'd like 2-3 ACKs before pushing upstream. Note that this doesn't handle auto-builds but we can add that later.
ACK! Please also document (I guess in README on master branch) exactly how the contents of the gh-pages branch can be generated / updated - even if it's something a CI job ends up doing.
This looks like a good proposal. +1
Also, about documenting this procedure on README.md, we can either: 1. document this on the GH wiki 2. Add it to README.md of the gh-pages branch instead of the master branch
I prefer the dev branch to contain README that actually matters for development or usage of the repo/product. I try to keep the README as brief as possible
@dmoluguw and @ftweedal -- I'll add the documentation to the already-open PR here: https://github.com/dogtagpki/jss/pull/36
That PR introduces a new docs/ folder which can contain both developer-facing and user-facing docs.
Adding this branch upstream... Thanks all!
This is documented upstream now: https://github.com/dogtagpki/jss/blob/master/docs/gh_pages.md
Marking this as fixed. :)
Metadata Update from @cipherboy: - Issue close_status updated to: fixed - Issue status updated to: Closed (was: Open)
Metadata Update from @cipherboy: - Issue assigned to cipherboy
@cipherboy I don't see anything at https://dogtagpki.github.io/jss/ yet...
Yeah, Matt was looking at it but we weren't able to get the gh-pages working. I don't have admin on the repo so I can't play around with it.
@mharmsen has fixed it by setting a Jekyll theme.
Login to comment on this ticket.