title: Using github actions to publish documentation
body: <p>What I considered:</p>
  <ul>
  <li>github offers github pages to host documentation in either a folder on my <code>master</code> branch or a dedicated <code>gh-pages</code> branch, but that would mean to commit build artifacts</li>
  <li>I can also let <code>readthedocs</code> build and host docs for me through webhooks, but that means learning how to configure Yet Another Tool at a point in time where I try to consolidate everything related to my project in <code>github-actions</code></li>
  </ul>
  <p>I already have a docu-building process that works for me (using <code>sphinx</code> as the builder) and that I can also test locally, so I'd rather just leverage that instead. It has all the rules set up and drops some static <code>html</code> in an artifact - it just doesn't get served anywhere. Handling it in the workflow, where all the other deployment configuration of my project is living, feels better than scattering it over different tools or github specific options.</p>
  <p>Is there already an action in the marketplace that allows me to do something like this?</p>
  <pre class="lang-yaml prettyprint-override"><code>name: CI
  on: [push]
  jobs:
    
    ...  # do stuff like building my-project-v1.2.3.whl, testing, etc.
    
    release_docs:
      steps:
        - uses: actions/sphinx-to-pages@v1  # I wish this existed
          with:
            dependencies:
              - some-sphinx-extension
              - dist/my-project*.whl
            apidoc_args:
              - &quot;--no-toc&quot;
              - &quot;--module-first&quot;
              - &quot;-o docs/autodoc&quot;
              - &quot;src/my-project&quot;
            build-args:
              - &quot;docs&quot;
              - &quot;public&quot;  # the content of this folder will then be served at
                          # https://my_gh_name.github.io/my_project/
  </code></pre>
  <p>In other words, I'd like to still have control over how the build happens and where artifacts are dropped, but do not want to need to handle the interaction with <code>readthedocs</code> or <code>github-pages</code>.</p>
  <hr />
  <p>###Actions that I tried</p>
  <p>❌ <a href="https://github.com/marketplace/actions/deploy-to-github-pages" rel="nofollow noreferrer">deploy-to-github-pages</a>: runs the docs build in an npm container - will be inconvenient to make it work with python and sphinx</p>
  <p>❌ <a href="https://github.com/marketplace/actions/gh-pages-for-github-action" rel="nofollow noreferrer">gh-pages-for-github-action</a>: no documentation</p>
  <p>❌ <a href="https://github.com/marketplace/actions/gh-pages-deploy" rel="nofollow noreferrer">gh-pages-deploy</a>: <s>seems to target host envs like jekyll instead of static content, and</s> correct usage with yml syntax not yet documented - I tried a little and couldn't get it to work</p>
  <p>❌ <a href="https://github.com/marketplace/actions/github-pages-deploy" rel="nofollow noreferrer">github-pages-deploy</a>: looks good, but correct usage with yml syntax not yet documented</p>
  <hr />
  <p>✅ <a href="https://github.com/marketplace/actions/github-pages" rel="nofollow noreferrer">github-pages</a>: needs a custom <a href="https://help.github.com/en/articles/creating-a-personal-access-token-for-the-command-line" rel="nofollow noreferrer">PAT</a> in order to trigger rebuilds (which is inconvenient) and <a href="https://github.com/a-recknagel/stenotype/issues/7" rel="nofollow noreferrer">uploads broken html</a> (which is bad, but might be my fault)</p>
  <p>✅ <a href="https://github.com/marketplace/actions/deploy-action-for-github-pages" rel="nofollow noreferrer">deploy-action-for-github-pages</a>: also works, and looks a little cleaner in the logs. Same limitations as the upper solution though, it needs a PAT and the served html is still broken.</p>
  <hr />
  <p>The eleven other results when searching for <a href="https://github.com/marketplace?utf8=%E2%9C%93&amp;type=actions&amp;query=github+pages" rel="nofollow noreferrer">github+pages</a> on the action marketplace all look like they want to use their own builder, which sadly never happens to be sphinx.</p>