-
Notifications
You must be signed in to change notification settings - Fork 42
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
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. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I did not see anything wrong with the changes you made. There are however still enough things I do not know to about that I do not think I'm the right person to approve this
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.
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great work @CasperWA, happy to leave the final branch/release process up to you.
Shall we release 0.16.5 after this PR?
- 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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-pr
or 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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
$ 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-pages
branch has been "prepared". Which is a one-time event. (See "Next steps" below.)Use
mike
Update
mkdocs.yml
and 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
latest
version (aliasmaster
) with every push event to themaster
branch.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
# Changelog
will be added to the description.pre-commit
hooksThis PR adds a new local hook that runs the
invoke
taskcreate-api-reference-docs
with a new special option--pre-commit
.The
--pre-commit
option 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-commit
to include the following other hooks from thepre-commit-hooks
library as well:To learn more about what the hooks do see the
pre-commit-hooks
README.The
trailing-whitespace
has also been updated to support markdown files, but respect the double end-of-the-line whitespace syntax.Finally, the
black
hook version has been updated.Next steps
The following steps are necessary for this PR to be able to be merged:
mike
manually to setup a test branch to be used to setup the framework and initial testing.latest
as long as we're in v0 andstable
when we get to v1.gh-pages
branch with the fully working and setup test branch.Alternatively, we can change the target deploy branch from
gh-pages
to 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).