Hosting Sphinx on GitHub Pages
==============================

While you can install Sphinx on your laptop and build documentation locally, ultimately you will want to share docs via a web server.
To do this, we will go over:


1. Setting up GitHub pages for a repository
2. Using GitHub Workflows to automate building documentation

1. Set up GitHub Pages
======================
GitHub Pages allow users to view web pages generated by our documentation. 
While there already a page set up for the :code:`sphinx-documentation-demo` project, you will need to do the following steps for a new project:

1a. Navigate to Page settings
-----------------------------
.. figure:: images/guide_install_repo_settings.png
    :class: sd-border-2

    Click the Settings tab in the project you want to add to GitHub Pages.


.. figure:: images/guide_install_repo_page_tab.png
    :class: sd-border-2

    Click the Pages tab (in the left sidebar) in the Settings page.


1b. Select branch to use with GitHub Pages 
------------------------------------------
.. warning::

    The GitHub repo must be **public** in order for it to be accessible via GitHub Pages.

.. figure:: images/guide_install_page_branch.png
    :class: sd-border-2

    When documentation is successfully deployed, you will see a link that looks like :code:`A`. For a new repo, this will not be active.
    You will need to set the branch (see :code:`B`). 
    This demo uses a separate branch called :code:`gh-pages` to deploy documentation. 

2. Using GitHub Workflow to Build Documentation
===============================================
GitHub can automatically discover workflows located in the :code:`.github/workflows` directory within the project directory.
We will be using a workflow to build documentation whenever a **new commit is pushed to the repository**.

2a. Example Workflow
--------------------
We will be reviewing the workflow that :code:`sphinx-documentation-demo` uses.

You can find the workflow in :code:`sphinx-documentation-demo/.github/workflows/documentation.yml`

.. code-block:: 
    :emphasize-lines: 16,19,24,26
    :linenos:

    name: documentation

    on: [push, pull_request, workflow_dispatch]

    permissions:
    contents: write

    jobs:
    docs:
        runs-on: ubuntu-latest
        steps:
        - uses: actions/checkout@v3
        - uses: actions/setup-python@v3
        - name: Install dependencies
            run: |
            pip install sphinx pydata-sphinx-theme sphinx-design sphinx-copybutton sphinx-autoapi
        - name: Sphinx build
            run: |
            sphinx-build docs _build
        - name: Deploy to GitHub Pages
            uses: peaceiris/actions-gh-pages@v3
            if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
            with:
            publish_branch: gh-pages
            github_token: ${{ secrets.GITHUB_TOKEN }}
            publish_dir: _build/
            force_orphan: true


* **Line 16.** Install dependencies
   * This tells GitHub to install sphinx and its dependencies to the ubuntu image. 
   * **Note**: After you add a new sphinx extension to :code:`pyproject.toml` and to :code:`docs/conf.py`, you'll also need to add the dependency to the list on line 16.
* **Line 19.** Build Docs
   * This runs :code:`sphinx-build` on the :code:`docs/` directory (in the repo) and creates the :code:`_build/` directory.
* Line 24. Publish to branch 
   * After building the docs, this line tells GitHub to publish the changes to the :code:`gh-pages` branch.
   * **Note**: this needs to be the same branch that GitHub Pages is set to publish with.
* **Line 26.** Specify directory to publish
   * This informs GitHub Pages where the static HTML documentation (built by :code:`sphinx-build`) is located.


3. Verifying GitHub Workflow Actions
====================================
Using the previously mentioned workflow, a GitHub Action will be triggered whenever a commit is pushed to the repo.
You can monitor running jobs from your GitHub Repository. 

.. figure:: images/guide_install_github_actions_tab.png
    :class: sd-border-2

    Click on the :code:`Actions` tab.

.. figure:: images/guide_install_actions_build.png
    :class: sd-border-2

    Current and previous workflow runs are listed in the Actions tab.
    The color of the icon indicates the current status of the run.
    You may notice a :code:`pages build and deployment` job running. This is reponsible for building the docs.

.. figure:: images/guide_install_actions_error.png
    :class: sd-border-2

    A red icon indicates that the run has failed. You can click on a run to get debug info for each step.
    Featured in this figure is a very common error: sphinx is missing an extension because it was not installed in the :code:`documentation.yml` workflow.

    To fix this, :code:`sphinx-copybutton` had to be added to line 16 in :code:`documentation.yml` (see :ref:`2a. Example Workflow`)