Automate versioned documentation #951
Conversation
Codecov Report
@@ Coverage Diff @@
## master #951 +/- ##
=======================================
Coverage 92.92% 92.92%
=======================================
Files 67 67
Lines 3787 3787
=======================================
Hits 3519 3519
Misses 268 268
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report at Codecov.
|
|
The |
|
馃槏 |
|
Looks great so far @CasperWA, this is something I've been wanting to find the time for too. Could we perhaps prepare this in a fork so we can actually do the gh pages builds without bringing down our current docs? I was able to do this for the providers dashboard after I enabled gh pages in my fork repo (in the normal way). |
|
Concerning the list of documentation version I suggest the following:
After making a new release, say v0.17.0, the list of versions will then be:
As a note, the aliases will have their own folder in the |
Yup. Just did it in another project and thought this was the right time to implement it here as well :)
Yeah, all the testing can be done in a separate branch. We can create a Edit: I.e., no need to use a fork - we can just momentarily change the target branch for all deployment for testing - and then "fix" it afterwards? |
Sounds good to me!
That also works. |
|
This might potentially "solve" this |
|
I've tested the workflow extensively in the OPTIMADE Gateway repository, and it all seems to be working nicely. I'll update this, go over the setup again and align with the OPTIMADE Gateway setup and mark this as "ready for review". |
Checking that they actually point to the latest full version number.
This will deploy and update the `latest` version (alias `master`) whenever a push event to `master` happens. It will not update the CHANGELOG or other things. Indeed, it will fail if the API Reference in the documentation has not been properly updated. The "regular" CD workflow has been updated with versioned documentation deployment, as well as a new feature: The release description on GitHub will be updated with the changelog for that particular version. This changelog will be *appended* to the existing description. One should now make sure to have a proper 1st level markdown header in the description, since the appended changelog will introduce a similar level header: `# Changelog`.
Added: - check-symlinks - destroyed-symlinks - requirements-txt-fixer And changed settings for `trailing-whitespace` to utilize the `markdown-linebreak-ext` option instead of excluding README.md. This is better, since it will now find and correct single trailing white space, but not double (which is part of markdown syntax). To learn more about what the hooks do see: https://github.com/pre-commit/pre-commit-hooks#readme
Untracked files might be new files under the API Reference folder that reflect new modules.
Update various parts of the documentation update workflows to be similar to the tested workflows in the OPTIMADE Gateway.
CasperWA
force-pushed
the
cwa/close-724-versioning-docs
branch
from
beb9df1
to
072fb6b
Compare
|
To check out / review the "new" documentation one can do the following: $ git fetch origin
$ git branch cwa/close-724-versioning-docs origin/cwa/close-724-versioning-docs
$ git checkout cwa/close-724-versioning-docs
$ pip install -U pip setuptools wheel
$ pip install -U -e .[docs]
$ mike serve -r origin -b new-gh-pages
Starting server at http://localhost:8000/
Press Ctrl+C to quit.Then go to localhost:8000 and enjoy :) |
|
Important: Before merging this, the Also note, I have gone through all versions (tags) that implemented the documentation, i.e., all the way back to |
| - name: Deploy documentation | ||
| if: env.RELEASE_RUN == 'false' | ||
| run: mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest master |
There was a problem hiding this comment.
One minor worry with this, can we test the mike deploy (without pushing to master) inside pull requests?
There was a problem hiding this comment.
I'm not completely sure what you mean by "testing mike deploy inside pull requests"? Do you mean you wish to see the would-be documentation if the new changes are implemented?
If this is what you meant, then no, I think this is out-of-scope for mike.
However, one can always do:
$ mike build -b burner-branch-for-my-new-fancy-head-branch-for-a-pr
$ mike serve -b burner-branch-for-my-new-fancy-head-branch-for-a-pror simply just mkdocs serve - which I would probably recommend to use locally at all times instead of mike. mike should really only be used to deal with the versioned edition/branch of the documentation.
For a reviewer one would need to fetch and use the PR's head branch and test this locally of course.
If you want more of a look at the new docs in the PR we need to set something else up.
There was a problem hiding this comment.
$ git fetch origin $ git branch cwa/close-724-versioning-docs origin/cwa/close-724-versioning-docs $ git checkout cwa/close-724-versioning-docs $ pip install -U pip setuptools wheel $ pip install -U -e .[docs] $ mike serve -r origin -b new-gh-pages Starting server at http://localhost:8000/ Press Ctrl+C to quit.
I have followed these instructions and I got a fully functioning website, so it seems everything is OK.
Cheers. And sure - let's put everything to the test right away 馃槄 ..... 馃槵 |
Closes #724.
IMPORTANT: This PR cannot be merged until the
gh-pagesbranch has been "prepared". Which is a one-time event. (See "Next steps" below.)Use
mikeUpdate
mkdocs.ymland dependencies.Automated deployment
With this PR we will automate deployment of the documentation using
mike, meaning it will be versioned.In addition, we will update the documentation, specifically the
latestversion (aliasmaster) with every push event to themasterbranch.As a bonus I have added a couple of steps to the deployment workflow that appends the version's changelog to the GitHub release description.
To see an example of this go to OPTIMADE Gateway.
When using this, we should always have a 1st level markdown header in the description, since a
# Changelogwill be added to the description.pre-commithooksThis PR adds a new local hook that runs the
invoketaskcreate-api-reference-docswith a new special option--pre-commit.The
--pre-commitoption ensures the hook will "fail" if it has updated the API reference docs and they have not been added to the index/staged.I've allowed myself to extend
pre-committo include the following other hooks from thepre-commit-hookslibrary as well:To learn more about what the hooks do see the
pre-commit-hooksREADME.The
trailing-whitespacehas also been updated to support markdown files, but respect the double end-of-the-line whitespace syntax.Finally, the
blackhook version has been updated.Next steps
The following steps are necessary for this PR to be able to be merged:
mikemanually to setup a test branch to be used to setup the framework and initial testing.latestas long as we're in v0 andstablewhen we get to v1.gh-pagesbranch with the fully working and setup test branch.Alternatively, we can change the target deploy branch from
gh-pagesto the test branch and merge this to test the automated deployment - then "fix" it with another PR when we are satisfied.Note: Actual publishing on PyPI should be disabled for all testing (duh).