Skip to content
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

Publish documentation to GitHub Pages #1774

Merged
merged 2 commits into from
Oct 24, 2021
Merged

Publish documentation to GitHub Pages #1774

merged 2 commits into from
Oct 24, 2021

Conversation

ofek
Copy link
Contributor

@ofek ofek commented Oct 15, 2021

This makes it so release tags or any tag starting with publish-docs (for manual triggers if needed) will publish the documentation for the latest release on PyPI to GitHub Pages. Docs are also decompiled on pushes to master but not published just in case any errors eventually arise.

After the potential merge and manual trigger, you'd then go to https://github.com/mhammond/pywin32/settings/pages and choose the gh-pages branch in the dropdown. At that point you're all done and the docs will be available for viewing for free at https://mhammond.github.io/pywin32/.

Notes:

  1. Unlike http://timgolden.me.uk/pywin32-docs/, I made the root be http://timgolden.me.uk/pywin32-docs/PyWin32.html and there is no table of contents like http://timgolden.me.uk/pywin32-docs/contents.html. I assume he adds those.
  2. For some reason unlike my other sites, omitting the trailing slash at the end of the URL will not automatically redirect, so you may want to document it as https://mhammond.github.io/pywin32/index.html. fixed

@mhammond mhammond merged commit 5490139 into mhammond:main Oct 24, 2021
@mhammond
Copy link
Owner

Sorry for the delay, but this is awesome, thanks so much! I'll deal with adding links and manually triggering the first publish as I find time over the next few weeks, but I can't see any reason not to merge this now.

@HanslettTheDev
Copy link

I saw from the readme section that you need help untangling the docs, please what exactly? So I can help

@mhammond
Copy link
Owner

I saw from the readme section that you need help untangling the docs, please what exactly?

The docs are a mess - the main problems are:

  • Most docs are generated by an "autoduck" tool which targets htmlhelp. This requires obscure Windows SDKs, can't be run on CI, etc - the github "publish docs" flow can't even build the docs - the best it can do it decompile the htmlhelp file.
  • There's no sane place to add new docs, and no support for things like markdown, and integrating with the autoduck docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants