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

migrate JBrowse configuration guide from github wiki to github pages #1153

Closed
rbuels opened this Issue Aug 1, 2018 · 7 comments

Comments

Projects
None yet
4 participants
@rbuels
Collaborator

rbuels commented Aug 1, 2018

No description provided.

@rbuels rbuels added this to the 1.16.0 milestone Aug 1, 2018

@cmdcolin

This comment has been minimized.

Show comment
Hide comment
@cmdcolin

cmdcolin Aug 3, 2018

Contributor

I am considering extending the scope of this to potentially replace all of JBrowse homepage.

The platform I'm aiming at for documentation switch is currently https://docusaurus.io/

During the port to this platform it seemed sort of natural to port the JBrowse homepage and documentation simultaneously

Therefore I made this demo site

http://cmdcolin.github.io/jbrowse_docs/

Currently, the configuration guide, FAQ, homepage, and all blogposts are transferred over to here

I'd be curious about any feedback at this early stage of evolution and about whether dropping wordpress seems viable, especially from @enuggetry @ihh @rbuels

I think that the end goal would be to:

  • finish porting existing documentation to docusaurus
  • rewrite quick-start guide for #1137
  • add automatic deployment of documentation from this github repo to jbrowse.org via Travis-CI (this would be done by doing an upload to EC2 rather than switching to github pages, because there is some infrastructure on EC2 that needs to be maintained)
  • remove or deactivate the wordpress from jbrowse.org and make sure we aren't losing anything
  • make sure that links to releases, documentation, etc. are not broken
  • probably break configuration guide into multiple pages based on sub-topics
Contributor

cmdcolin commented Aug 3, 2018

I am considering extending the scope of this to potentially replace all of JBrowse homepage.

The platform I'm aiming at for documentation switch is currently https://docusaurus.io/

During the port to this platform it seemed sort of natural to port the JBrowse homepage and documentation simultaneously

Therefore I made this demo site

http://cmdcolin.github.io/jbrowse_docs/

Currently, the configuration guide, FAQ, homepage, and all blogposts are transferred over to here

I'd be curious about any feedback at this early stage of evolution and about whether dropping wordpress seems viable, especially from @enuggetry @ihh @rbuels

I think that the end goal would be to:

  • finish porting existing documentation to docusaurus
  • rewrite quick-start guide for #1137
  • add automatic deployment of documentation from this github repo to jbrowse.org via Travis-CI (this would be done by doing an upload to EC2 rather than switching to github pages, because there is some infrastructure on EC2 that needs to be maintained)
  • remove or deactivate the wordpress from jbrowse.org and make sure we aren't losing anything
  • make sure that links to releases, documentation, etc. are not broken
  • probably break configuration guide into multiple pages based on sub-topics
@rbuels

This comment has been minimized.

Show comment
Hide comment
@rbuels

rbuels Aug 3, 2018

Collaborator

@ihh in particular have a look at http://cmdcolin.github.io/jbrowse_docs/ and http://docusaurus.io

The wordpress deactivation and cutover to a docusaurus-and-git model of maintaining jbrowse.org will happen sometime next week under this current trajectory.

Collaborator

rbuels commented Aug 3, 2018

@ihh in particular have a look at http://cmdcolin.github.io/jbrowse_docs/ and http://docusaurus.io

The wordpress deactivation and cutover to a docusaurus-and-git model of maintaining jbrowse.org will happen sometime next week under this current trajectory.

@cmdcolin

This comment has been minimized.

Show comment
Hide comment
@cmdcolin

cmdcolin Aug 6, 2018

Contributor

I'm pretty happy with look and feel of the website currently! It's not a dramatic redesign as it keeps a lot of the same layout and content, but let me know what you think!

I have automatic upload to ec2 instance working too.

I'm still trying to see what to do about release announcement blogposts too. Since docusaurus would be contained in this repo, it might be good to have an autogenerated blogpost. I imagine it would use Travis to create the git commit that makes the blogpost. Haven't decided where "extra announcement" content of the blogpost would be stored if there is any (maybe in commit message?)

Contributor

cmdcolin commented Aug 6, 2018

I'm pretty happy with look and feel of the website currently! It's not a dramatic redesign as it keeps a lot of the same layout and content, but let me know what you think!

I have automatic upload to ec2 instance working too.

I'm still trying to see what to do about release announcement blogposts too. Since docusaurus would be contained in this repo, it might be good to have an autogenerated blogpost. I imagine it would use Travis to create the git commit that makes the blogpost. Haven't decided where "extra announcement" content of the blogpost would be stored if there is any (maybe in commit message?)

@cmdcolin

This comment has been minimized.

Show comment
Hide comment
@cmdcolin

cmdcolin Aug 8, 2018

Contributor

List of progress

  • Automated blog post: I might say this could be delayed. Manual composition of the blog seems like it would be easier for now. Especially if a requirement is that the blog contains checksums. Maybe instead small checksum file can be uploaded to github releases, that could make it easier.

  • Quick start guide: I spearheaded this but certainly there could be debate about the delivery. Please review

  • Link checking: could be ongoing, could involve mod_rewrite on jbrowse.org server (e.g. should an old URL to download.php be remapped to a new valid file URL?)

  • Remove or deactivate wordpress: I have not done this but the infrastructure is now in place to easily swap in docusaurus so I think it should be ready

  • What to do with existing gmod.org docs, existing quick start guide in docs/tutorial

  • Finish porting docs: As far as I know this is done

  • Breaking config guide into sections has been mostly done! Potentially a newer organization could be applied if it improves user comprehension

  • Automatic deployment to EC2: done via encryption of upload key (standard travis encrypt --add) plus rsync of built docusaurus directory. note that I checked and encrypted variables arent available to PR so this is secure https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions

Contributor

cmdcolin commented Aug 8, 2018

List of progress

  • Automated blog post: I might say this could be delayed. Manual composition of the blog seems like it would be easier for now. Especially if a requirement is that the blog contains checksums. Maybe instead small checksum file can be uploaded to github releases, that could make it easier.

  • Quick start guide: I spearheaded this but certainly there could be debate about the delivery. Please review

  • Link checking: could be ongoing, could involve mod_rewrite on jbrowse.org server (e.g. should an old URL to download.php be remapped to a new valid file URL?)

  • Remove or deactivate wordpress: I have not done this but the infrastructure is now in place to easily swap in docusaurus so I think it should be ready

  • What to do with existing gmod.org docs, existing quick start guide in docs/tutorial

  • Finish porting docs: As far as I know this is done

  • Breaking config guide into sections has been mostly done! Potentially a newer organization could be applied if it improves user comprehension

  • Automatic deployment to EC2: done via encryption of upload key (standard travis encrypt --add) plus rsync of built docusaurus directory. note that I checked and encrypted variables arent available to PR so this is secure https://docs.travis-ci.com/user/pull-requests/#pull-requests-and-security-restrictions

@ihh

This comment has been minimized.

Show comment
Hide comment
@ihh

ihh Aug 8, 2018

Member

This looks amazing - let's talk about it next week

Member

ihh commented Aug 8, 2018

This looks amazing - let's talk about it next week

@cmdcolin

This comment has been minimized.

Show comment
Hide comment
@cmdcolin

cmdcolin Aug 8, 2018

Contributor

Thanks! Potential items:

  • update website before release: we can use a commit message with "[update docs]" or "[update docs only]" to skip tests
  • making auto blogposts: during dev chat we decided to kick this down the road. could be incorporated into release.sh though
  • checksums: we might not keep doing checksums, at least not in blogposts because there is a chicken and the egg thing with the post being built
  • allow changes to docs that don't update website before release. not as easy as just not doing "[update docs]" because a "[update docs]" down the line will kick them live
  • versioned docs, to do or not to do
Contributor

cmdcolin commented Aug 8, 2018

Thanks! Potential items:

  • update website before release: we can use a commit message with "[update docs]" or "[update docs only]" to skip tests
  • making auto blogposts: during dev chat we decided to kick this down the road. could be incorporated into release.sh though
  • checksums: we might not keep doing checksums, at least not in blogposts because there is a chicken and the egg thing with the post being built
  • allow changes to docs that don't update website before release. not as easy as just not doing "[update docs]" because a "[update docs]" down the line will kick them live
  • versioned docs, to do or not to do
@nathanhaigh

This comment has been minimized.

Show comment
Hide comment
@nathanhaigh

nathanhaigh Aug 8, 2018

Contributor

@cmdcolin can tags/branches be used to test docs before going live on the webpage or provide a "latest" version much like readthedocs does?

Contributor

nathanhaigh commented Aug 8, 2018

@cmdcolin can tags/branches be used to test docs before going live on the webpage or provide a "latest" version much like readthedocs does?

@rbuels rbuels closed this Aug 16, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment