{"id":21401160,"url":"https://github.com/uibcdf/action-sphinx-docs-to-gh-pages","last_synced_at":"2025-07-13T21:31:34.866Z","repository":{"id":39625529,"uuid":"378995464","full_name":"uibcdf/action-sphinx-docs-to-gh-pages","owner":"uibcdf","description":"GitHub Action: The sphinx documentation in a repository is compiled and deployed to GitHub Pages through the gh-pages branch.","archived":false,"fork":false,"pushed_at":"2024-01-23T22:44:22.000Z","size":37,"stargazers_count":14,"open_issues_count":1,"forks_count":7,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-04-24T10:14:45.233Z","etag":null,"topics":["actions","github-actions"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uibcdf.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-21T16:28:54.000Z","updated_at":"2024-06-19T05:30:38.526Z","dependencies_parsed_at":"2024-01-23T19:05:18.890Z","dependency_job_id":"e91f7ec9-d559-4416-87a8-66432da4302a","html_url":"https://github.com/uibcdf/action-sphinx-docs-to-gh-pages","commit_stats":{"total_commits":53,"total_committers":4,"mean_commits":13.25,"dds":0.09433962264150941,"last_synced_commit":"bc30e808781d42d386d302aed16fd91582086bb4"},"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uibcdf%2Faction-sphinx-docs-to-gh-pages","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uibcdf%2Faction-sphinx-docs-to-gh-pages/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uibcdf%2Faction-sphinx-docs-to-gh-pages/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uibcdf%2Faction-sphinx-docs-to-gh-pages/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uibcdf","download_url":"https://codeload.github.com/uibcdf/action-sphinx-docs-to-gh-pages/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225919233,"owners_count":17545210,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["actions","github-actions"],"created_at":"2024-11-22T15:26:24.291Z","updated_at":"2024-11-22T15:26:24.992Z","avatar_url":"https://github.com/uibcdf.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# action-sphinx-docs-to-gh-pages\n[![Open Source Love](https://badges.frapsoft.com/os/v2/open-source.svg?v=103)](https://github.com/ellerbrock/open-source-badges/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n\nThe [Sphinx](https://www.sphinx-doc.org/en/master/) documentation in a repository is automatically compiled as 'html'\nand deployed, by means of the `gh-pages` branch, with this [GitHub Actions](https://github.com/features/actions) to\n[GitHub Pages](https://pages.github.com/). The user has only to be sure that the repository accomplishes [a couple of\nrequirements](#Requirements).\n\nIn summary, this GitHub action does the following:\n\n- Takes the author and SHA id of the trigger action (`push` or `pull request`) to be consistent along the action.\n- Creates a new `gh-pages` branch if this is not already in the repository.\n- Compiles the sphinx documentation in the directory and branch specified by the user.\n- Pushes the output html documentation to the `gh-pages` branch.\n\nThis GitHub Action was developed by [the Computational Biology and Drug Design Research Unit -UIBCDF- at the\nMexico City Children's Hospital Federico Gómez](https://www.uibcdf.org/) (see also\n[Contributers](https://github.com/uibcdf/action-sphinx-docs-to-gh-pages/graphs/contributors)). Other GitHub Actions can\nbe found at [the UIBCDF GitHub site](https://github.com/search?q=topic%3Agithub-actions+org%3Auibcdf\u0026type=Repositories).\n\n## Requirements\n\n### GitHub Pages taking the source from the branch gh-pages\n\nThere is no need to have a `gh-pages` branch already in the repository. This action will create it for you. But once\nthis GitHub action runned for first time, make sure that GitHub Pages is taking the web source code from the branch\n`gh-pages`. In the github repository go to 'Settings -\u003e Pages -\u003e Source' and check that no other branch is selected as\nsource.\n\n### A YAML file to create a conda environment with docs compilation dependencies\n\nThe compilation of your sphinx documentation requires dependencies that can be solved with a\ntemporary conda environment. Make sure that the repository has a Yaml file with the details to make\nthis environment (see the section [\"Documentation conda environment\"](#Documentation-conda-environment)).\n\n## How to use it\n\nTo include this GitHub Action, create a [YAML](https://yaml.org/) file (named `sphinx_docs_to_gh_pages.yaml`, for instance)\nwith the following content in the directory `.github/workflows` of your repository:\n\n```yaml\nname: Sphinx docs to gh-pages\n\non:\n  push:\n    branches:\n      - main\n\n# workflow_dispatch:        # Un comment line if you also want to trigger action manually\n\njobs:\n  sphinx_docs_to_gh-pages:\n    runs-on: ubuntu-latest\n    name: Sphinx docs to gh-pages\n    steps:\n      - uses: actions/checkout@v3\n        with:\n          fetch-depth: 0\n      - name: Make conda environment\n        uses: conda-incubator/setup-miniconda@v2\n        with:\n          python-version: 3.10    # Python version to build the html sphinx documentation\n          environment-file: devtools/conda-envs/docs_env.yaml    # Path to the documentation conda environment\n          auto-update-conda: false\n          auto-activate-base: false\n          show-channel-urls: true\n      - name: Installing the library\n        shell: bash -l {0}\n        run: |\n          python setup.py install\n      - name: Running the Sphinx to gh-pages Action\n        uses: uibcdf/action-sphinx-docs-to-gh-pages@v2.1.0\n        with:\n          branch: main\n          dir_docs: docs\n          sphinx-apidoc-opts: '--separate -o . ../'\n          sphinx-apidoc-exclude: '../*setup* ../*.ipynb'\n          sphinx-opts: ''\n```\n\nTwo things need to be known to run the GitHub Actions without further work: the meaning of the input parameters and the\nYAML file to make a temporary Conda environment where the sphinx documentation can be compiled.\n\n### Input parameters\n\nThese are the input parameters of the action:\n\n| Input parameters        | Description                                                                                         | Default value    |\n|-------------------------|-----------------------------------------------------------------------------------------------------|------------------|\n| `branch`                | Name of the branch where the sphinx documentation is located                                        | `main`           |\n| `branch-checkout-args`  | Arguments to pass to `git checkout`: `git checkout ${checkout-args} \"${branch}\"`                    | ''               |\n| `dir_docs`              | Path where the sphinx documentation is located                                                      | `docs`           |\n| `sphinx-apidoc`         | With sphinx-apidoc                                                                                  | true             |\n| `sphinx-apidoc-exclude` | With sphinx-apidoc                                                                                  | `*setup* tests*` |\n| `sphinx-apidoc-opts`    | Options for sphinx-apidoc (default outputs to dir_docs and searches for modules one level up)       | '-o . ../'       |\n| `sphinx-opts`           | Compilation options for sphinx-build                                                                | ''               |\n\nThey are placed in the last lines of the above workflow example file:\n\n```yaml\n      - name: Running the Sphinx to gh-pages Action\n        uses: uibcdf/action-sphinx-docs-to-gh-pages@v2.1.0\n          with:\n            branch: main\n            dir_docs: docs\n            sphinx-opts: ''\n            sphinx-apidoc-opts: '--separate -o . ../'\n            sphinx-apidoc-exclude: '../*.ipynb'\n```\n\nIn case your sphinx documentation is placed in a directory named 'docs' in the 'main' branch to be\ncompiled with no further options, you can do without the section `with:`.\n\n### Documentation Requirements\n\nThe Sphinx documentation will need specific libraries and packages to be compiled. There are a few options to achieving\nthis, one is to create a [Conda](https://docs.conda.io/en/latest/) environment in which to build the\ndocumentation. Alternatively if your package includes the `[options.extras_require] docs` section you can install these.\n\n#### Conda environment\n\nThey can be specified in a Conda environment file. This way, a temporary enviroment can be made and activated\nto compile the documentation with all dependencies satisfied. Write a file in the repository with\nthe following content:\n\n```yaml\nname: docs\n\nchannels:\n\n  - conda-forge\n  - defaults\n\ndependencies:\n\n  # Write here all dependencies to compile the sphinx documentation.\n  # This list is just an example\n  - python=3.10\n  - sphinx\n  - sphinx_rtd_theme\n  - sphinxcontrib-bibtex\n  - nbsphinx\n  - recommonmark\n  - sphinx-markdown-tables\n```\n\nAnd replace the value of the workflow input parameter `environment-file:` with the right path to your documentation conda enviroment file. In\nthe case of [the above example](#How-to-use-it) ('devtools/conda-envs/docs\\_env.yaml'):\n\n```yaml\njobs:\n  sphinx_docs_to_gh-pages:\n    steps:\n      - name: Make conda environment\n        uses: conda-incubator/setup-miniconda@v2\n        with:\n          # Replace with the path to your documentation conda enviroment file\n          environment-file: devtools/conda-envs/docs_env.yaml\n```\n\n#### `setup.cfg`\n\nMany Python packages use [setuptools]() for configuring installation via the `setup.cfg` file. One section of this is\nthe `[options.extras_require]` where packages not required for running the package but used in testing or building\ndocumentation can be listed. To list your documentation build requirements add the following to your `setup.cfg`\n\n``` cfg\n[options.extras_require]\n\ndocs =\n  sphinx\u003c5.0\n  myst_parser\n  pydata_sphinx_theme\n  sphinx_markdown_tables\n  sphinx_rtd_theme\n  sphinxcontrib-mermaid\n```\n\nThen in your `sphinx_docx_to_gh_pages.yaml` that you have created under the `.github/workflows/` directory replace the\nstep with `-name Make conda environment` (see above example) with the following steps which will setup the specified\nPython version and then install the docs requirements listed in your `setup.cfg`.\n\n``` yaml\njobs:\n  sphinx_docs_to_gh-pages:\n    steps:\n      - name: Setup Python\n        uses: actions/setup-python@v2\n        with:\n          python-version: 3.10\n      - name: Installing the Documentation requirements\n        run: |\n          pip3 install .[docs]\n```\n\n## Other tools like this one\n\nThis GitHub Action was developed to solve a need of the [UIBCDF]((https://www.uibcdf.org/)). And to be used,\nadditionally, as an example of house-made GitHub Action for researchers and students in this lab.\n\nOther tools you can find in the market doing these same tasks are mentioned below. We recognize and\nthank the work of their developers. Many of those GitHub Actions were used by us to learn how to set up our own one.\n\nIf you think that your GitHub Action should be mentioned here, fell free to PR with a new line.\n\n### Sphinx\n\n* [sphinx-pages](https://github.com/seanzhengw/sphinx-pages)\n* [spinx-action](https://github.com/ammaraskar/sphinx-action)\n* [action-sphinx-composite](https://github.com/rickstaa/action-sphinx-composite)\n\n### GitHub Pages\n\n* [gh-pages-action](https://github.com/axetroy/gh-pages-action)\n* [github-pages-deploy-action](https://github.com/JamesIves/github-pages-deploy-action)\n* [GitHub-Pages-deploy](https://github.com/Cecilapp/GitHub-Pages-deploy)\n* [create-ghpages-ifnotexists](https://github.com/ChristopherDavenport/create-ghpages-ifnotexists)\n* [simple-github-pages-deploy-action](https://github.com/rdarida/simple-github-pages-deploy-action)\n* [gh-pages-action](https://github.com/axetroy/gh-pages-action)\n* [ghaction-github-pages](https://github.com/crazy-max/ghaction-github-pages)\n* [actions-gh-pages](https://github.com/peaceiris/actions-gh-pages)\n\n### GitHub Push\n\n* [github-push-action](https://github.com/ad-m/github-push-action)\n\n### Shinx + GitHub Pages\n\n* [pages](https://github.com/sphinx-notes/pages)\n* [spinx-pages](https://github.com/seanzhengw/sphinx-pages)\n\n## Links\n\n* [GitHub Pages](https://pages.github.com/)\n* [GitHub Actions](https://github.com/features/actions)\n* [Sphinx](https://www.sphinx-doc.org/en/master/)\n* [YAML](https://yaml.org/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuibcdf%2Faction-sphinx-docs-to-gh-pages","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuibcdf%2Faction-sphinx-docs-to-gh-pages","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuibcdf%2Faction-sphinx-docs-to-gh-pages/lists"}