Versioned documenation hosting

[yardasol]

Summary of changes

This PR enables versioned documentation on the github pages website. You'll need to clone the repo and build the website yourself using the included doc_environment.yml file to get all the necessary packages.

Specifically, this PR

• Splits the monolithic environment.yml file into a build/test verison (environment.yml) and a documentation version (doc/doc_environment.yml), and use each in their respective workflow
• Adds the sphinx-multiversion and sphinxcontib-apidoc packages to the conda environment in the deploy-docs workflow
• Adds configuration options for the above packages to doc/conf.py
• Updates the instructions to build the docs in the readme using the new doc/conf.py file.
• Adds an html sidebar template for a read-the-docs style version selection menu (doc/_templates/versions.html)
• Tightens up the triggers for our workflows:
  • deploy-docs now can be triggered by releases
  • cache-dependencies now makes separate dependency caches for the new environment.yml dependencies and the doc_environment.yml dependencies.
  • test-saltproc now only runs when pushes to the source code and tests are made.
• Adds manual triggers for all workflows.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Required for Merging

• I have read the CONTRIBUTING document.
• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.
  • CI tests pass
  • Local tests pass (including Serpent2 integration tests)

Associated Issues and PRs

• Issue: closes Feature: Add versioned documentation #102
• Issue: closes do not merge any PRs after #95 until a versioned documentation is set up #103
• Issue: closes if we end up seeing long build times, we can have a test_environment.yml and a docs_environment.yml file separately and use them in the different builds. #107
• PR 62 in sphinx-multiversion was useful in getting things to work, althought I didn't end up actually using that version of the code.

Associated Developers

• Dev: @munkm

Checklist for Reviewers

Reviewers should use this link to get to the
Review Checklist before they begin their review.

[pep8speaks]

Hello @yardasol! Thanks for updating this PR. We checked the lines you've touched for PEP 8 issues, and found:

• In the file doc/conf.py:

Line 23:1: E402 module level import not at top of file

Comment last updated at 2022-01-28 22:52:32 UTC

[yardasol]

@pep8speaks is saying that the from saltproc.version import __version__ statment needs to be at the top of the file, but we need to add saltproc to the syspath before we are able to execute tthe statement!

[LukeSeifert]

I'm not familiar with YAML, but the code looks good to me. However, when I tried following the build directions given in the readme, I got an error. When I changed to the master branch and followed those directions, I did not get an error and was able to build successfully. I included the error message I got here:

Running Sphinx v2.4.0

Extension error:
Could not import extension sphinxcontrib.apidoc (exception: No module named 'sphinxcontrib.apidoc')
Makefile:53: recipe for target 'html' failed
make: *** [html] Error 2

[yardasol]

@LukeSeifert Did you make a conda environment from the doc-environent.yml file? Regardless, I think I do need to specify that user's will need to install the conda environment to build the docs.

[yardasol]

@munkm is the language I use to describe conda vs mamba appropriate and neutral? Don't want to ruffle any feathers...

[yardasol]

@LukeSeifert I changed the instructions. Could you try it again and let me know?

[munkm]

A few minor comments!

[munkm]

For the future, you can import the readme in the docs so that you don't have to repeat the same info twice. That way both don't need to be updated if something changes.

[yardasol]

The formatting for the .rst files and the .md files is slightly different. I'll need to think of a solution to this later.

[munkm]

There are a few other env tools that exist. You should be explicit here that these directions are assuming a conda environment and we haven't tried it with another manager (and don't necessarily recommend it).

[munkm]

Suggested change

	repository:
	repository (and assuming the environment has been activated):

[munkm]

are you sure you want all messages to go to your personal email? We could make a mailing list.

[yardasol]

Let's make a mailing list. I'll revert back to the googlegroups email here

[munkm]

@munkm is the language I use to describe conda vs mamba appropriate and neutral? Don't want to ruffle any feathers...

Yes I think your language is good!