Update documentation to use pdoc
and refresh automatically using github action.
#29
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
The current documentation in https://google.github.io/mediapy/ was created using
pdoc3
which was a fork ofpdoc
. The documentation was updated manually (and infrequently) by writing to agh-pages
branch in the repo --- a cumbersome process.The maintainers of
pdoc
have been very active and so it is now worthwhile to transition to that package.See the discussion at the end of https://github.com/mitmproxy/pdoc .
The new
mediapy
documentation can be previewed at https://hhoppe.github.io/mediapy/(That view is still not showing some logo images because these are awaiting their commits into the main https://github.com/google/mediapy/ repo.)
One issue with
pdoc
(andpdoc3
) is that they expand all type information -- see mitmproxy/pdoc#420 . This PR avoids the problem by introducing temporary typenames and applying some postprocessing. Hopefully this can be simplified in the future.To enable web deployment of the new documentation, it is necessary to change the GitHub repo setting
Pages
to use as sourceGitHub Actions
rather thanDeploy from a branch: gh-pages
.Perhaps it is best to make this settings change before applying the PR to enable the
website
github action to operate correctly. And/or this may require an additional dummy commit.Once the new documentation is live, it will be possible to delete the
gh-pages
branch as that will no longer be needed.