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

[17.09] Migrate documentation for setting up a production instance to Galaxy. #5135

Merged
merged 2 commits into from Dec 6, 2017

Conversation

Projects
None yet
4 participants
@jmchilton
Member

jmchilton commented Dec 6, 2017

This is a bugfix for the soon to be introduced bug of missing documentation for 17.09 and before. 18.01 will require a significant rewrite of these pages for the uWSGI and configuration changes to Galaxy. Since we are now hosting older branches of these docs including the release_17.09, backporting this configuration documentation will allow us to provide permanent links to this 17.09 variant of all this documentation (with the final copy of information about Paste and galaxy.ini).

This content currently migrates 8 pages of important admin documentation.

The following 4 pages have been migrated to the main admin section of the Galaxy docs:

  • the production configuration page
  • the cluster configuration page
  • the job configuration page
  • the scaling information page

The following 4 pages have been migrated to the "special topics" admin section of the Galaxy docs:

  • the ftp configuration page
  • the top-level nginx page (for external auth content still linking out to the hub)
  • the top-level apache page (for external auth content still linking out to the hub)
  • the job metrics configuration page

This PR also includes small tweaks to sphinx documentation generation.

  • Add a quick build mode that skips source generation / Python docs (export GALAXY_DOCS_SKIP_SOURCE=1 to build this way). This speeds up review of core Sphinx docs.
  • Use AutoStructify for better Markdown integration.

Additionally this PR includes updates to this documentation above and beyond what is on the corresponding Hub pages to reflect more of the state of art as of 17.09 including:

  • Update the job configuration page with information about XML macros.
  • Mention and link to newer style resubmission condition expressions (not just an enumerated string anymore).
  • Updated list of dynamic job runner configuration parameters.
  • Mention the raw attribute for env directives in the job configuration page.
  • Mention the total_walltime limit added in #3217.
  • Drop mentions of older URL-based job conf configuration stuff.
  • Mention newer Local and Paramiko based shell runners in CLI section.
  • Mention newer slurm job styles in CLI section.
  • Improved Pulsar links.
  • Fix dataset security link in Apache display sites config.
  • Update job metrics page to link to a new Github issue instead of old Trello issues.
Migrate documentation for setting up a production instance to Galaxy.
This is a bugfix for the future bug of missing documentation for 17.09 and before. 18.01 will require a significant rewrite of these pages for the uWSGI and configuration changes to Galaxy and the release_17.09 branch of these docs is now being hosted https://docs.galaxyproject.org/en/release_17.09/, so backporting this configuration documentation will allow us to provide permenant links to this 17.09 varaint of all this documentation (with information about paste and galaxy.ini for instance).

This content currently includes:

- the production configuration page
- the cluster configuration page
- the job configuration page
- the scaling information page
- the ftp configuration page
- the top-level nginx page (for external auth content still linking out to the hub)
- the top-level apache page (for external auth content still linking out to the hub)
- the job metrics configuration page

Includes small tweaks to sphinx documentation generation.

- Add a quick build mode that skips source generation / Python docs (export GALAXY_DOCS_SKIP_SOURCE=1 to build this way). This speeds up review of core Sphinx docs.
- Use AutoStructify for better Markdown integration.

Updates to the documentation above and beyond what is on the corresponding Hub pages to reflect more of the state of art as of 17.09 including:

- Update the job configuration page with information about XML macros.
- Mention and link to newer style resubmission condition expressions (not just an enumerated string anymore).
- Updated list of dynamic job runner configuration parameters.
- Mention the ``raw`` attribute for ``env`` directives in the job configuration page.
- Mention the ``total_walltime`` limit added in #3217.
- Drop mentions of older URL-based job conf configuration stuff.
- Mention newer Local and Paramiko based shell runners in CLI section.
- Mention newer slurm job styles in CLI section.
- Improved Pulsar links.
- Fix dataset security link in Apache display sites config.
- Update job metrics page to link to a new Github issue instead of old Trello issues.
**The most up-to-date details of advanced job configuration features can be found in the [sample job_conf.xml](https://github.com/galaxyproject/galaxy/blob/dev/config/job_conf.xml.sample_advanced) found in the Galaxy distribution.**
### Galaxy Configuration

This comment has been minimized.

@erasche

erasche Dec 6, 2017

Member

level 1 -> level 3?

@erasche

This comment has been minimized.

Member

erasche commented Dec 6, 2017

👍

Rework headings in jobs docs.
Thanks to comment from @erasche review.
@erasche

erasche approved these changes Dec 6, 2017

@bgruening

This comment has been minimized.

Member

bgruening commented Dec 6, 2017

That's super cool, I was worried about this how we can document the new changes and keep the old ones. And this is clearly the way to go! I also like to keep the docs close to the source, I think we discussed this before but never did this move. Big thanks @jmchilton! This IS awesome!

@martenson

Great step in the direction we want to go - provide readthedocs-like experience for version-bound documentation. Next piece of the puzzle would probably be an actual DOM element that provides the version selector.

I think this is very important for the Oslo admin training and labeling missing docs as a bug seems appropriate.

Thank you John.

@martenson martenson merged commit b0c0324 into galaxyproject:release_17.09 Dec 6, 2017

6 checks passed

api test Build finished. 293 tests run, 4 skipped, 0 failed.
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
framework test Build finished. 162 tests run, 0 skipped, 0 failed.
Details
integration test Build finished. 46 tests run, 0 skipped, 0 failed.
Details
selenium test Build finished. No test results found.
Details
toolshed test Build finished. 579 tests run, 0 skipped, 0 failed.
Details

jmchilton added a commit to jmchilton/galaxy-hub that referenced this pull request Jan 3, 2018

Redirect 8 migrated admin topics to Galaxy docs.
More updated content is available in Galaxy docs as well as versioned information for different Galaxy's (currently 17.09 and dev). Added to Galaxy with galaxyproject/galaxy#5135.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment