{"id":13993661,"url":"https://github.com/ammaraskar/sphinx-action","last_synced_at":"2025-05-15T16:01:52.139Z","repository":{"id":39620575,"uuid":"205302903","full_name":"ammaraskar/sphinx-action","owner":"ammaraskar","description":"Github action that builds docs using sphinx and places errors inline","archived":false,"fork":false,"pushed_at":"2025-03-03T00:27:25.000Z","size":69,"stargazers_count":202,"open_issues_count":34,"forks_count":122,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-06T17:11:12.572Z","etag":null,"topics":["github-action","github-actions","sphinx","status-check"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ammaraskar.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,"zenodo":null}},"created_at":"2019-08-30T04:13:48.000Z","updated_at":"2025-04-09T01:33:24.000Z","dependencies_parsed_at":"2024-02-29T06:24:26.053Z","dependency_job_id":"2d4fc70d-470d-4d2d-89c2-b3a6202c6e1a","html_url":"https://github.com/ammaraskar/sphinx-action","commit_stats":{"total_commits":57,"total_committers":5,"mean_commits":11.4,"dds":0.08771929824561409,"last_synced_commit":"c61ac11d9ee097caf8983c10c8b5af5861b32b54"},"previous_names":[],"tags_count":96,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaraskar%2Fsphinx-action","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaraskar%2Fsphinx-action/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaraskar%2Fsphinx-action/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ammaraskar%2Fsphinx-action/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ammaraskar","download_url":"https://codeload.github.com/ammaraskar/sphinx-action/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254201874,"owners_count":22031636,"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":["github-action","github-actions","sphinx","status-check"],"created_at":"2024-08-09T14:02:29.572Z","updated_at":"2025-05-15T16:01:52.121Z","avatar_url":"https://github.com/ammaraskar.png","language":"Python","readme":"# Sphinx Build Action\n\n[![Build Status](https://travis-ci.org/ammaraskar/sphinx-action.svg?branch=master)](https://travis-ci.org/ammaraskar/sphinx-action)\n[![Test Coverage](https://codecov.io/gh/ammaraskar/sphinx-action/branch/master/graph/badge.svg)](https://codecov.io/gh/ammaraskar/sphinx-action)\n\n\nThis is a Github action that looks for Sphinx documentation folders in your\nproject. It builds the documentation using Sphinx and any errors in the build\nprocess are bubbled up as Github status checks.\n\nThe main purposes of this action are:\n\n* Run a CI test to ensure your documentation still builds. \n\n* Allow contributors to get build errors on simple doc changes inline on Github\n  without having to install Sphinx and build locally.\n  \n![Example Screenshot](https://i.imgur.com/Gk2W32O.png)\n\n## How to use\n\nCreate a workflow for the action, for example:\n\n```yaml\nname: \"Pull Request Docs Check\"\non: \n- pull_request\n\njobs:\n  docs:\n    runs-on: ubuntu-latest\n    steps:\n    - uses: actions/checkout@v1\n    - uses: ammaraskar/sphinx-action@master\n      with:\n        docs-folder: \"docs/\"\n```\n\n* You can choose a Sphinx version by using the appropriate tag. For example, to\n  specify Sphinx 7.0.0 you would use `ammaraskar/sphinx-action@7.0.0`. `master`\n  currently uses Sphinx 2.4.4.\n\n* If you have any Python dependencies that your project needs (themes, \nbuild tools, etc) then place them in a requirements.txt file inside your docs\nfolder.\n\n* If you have multiple sphinx documentation folders, please use multiple\n  `uses` blocks.\n\nFor a full example repo using this action including advanced usage, take a look\nat https://github.com/ammaraskar/sphinx-action-test\n\n## Great Actions to Pair With\n\nSome really good actions that work well with this one are\n[`actions/upload-artifact`](https://github.com/actions/upload-artifact)\nand [`ad-m/github-push-action`](https://github.com/ad-m/github-push-action).\n\nYou can use these to make built HTML and PDFs available as artifacts:\n\n```yaml\n    - uses: actions/upload-artifact@v1\n      with:\n        name: DocumentationHTML\n        path: docs/_build/html/\n```\n\nOr to push docs changes automatically to a `gh-pages` branch:\n\n\u003cdetails\u003e\u003csummary\u003eCode for your workflow\u003c/summary\u003e\n\u003cp\u003e\n\n```yaml\n    - name: Commit documentation changes\n      run: |\n        git clone https://github.com/your_git/repository.git --branch gh-pages --single-branch gh-pages\n        cp -r docs/_build/html/* gh-pages/\n        cd gh-pages\n        git config --local user.email \"action@github.com\"\n        git config --local user.name \"GitHub Action\"\n        git add .\n        git commit -m \"Update documentation\" -a || true\n        # The above command will fail if no changes were present, so we ignore\n        # the return code.\n    - name: Push changes\n      uses: ad-m/github-push-action@master\n      with:\n        branch: gh-pages\n        directory: gh-pages\n        github_token: ${{ secrets.GITHUB_TOKEN }}\n```\n\n\u003c/p\u003e\n\u003c/details\u003e\n\nFor a full fledged example of this in action take a look at:\nhttps://github.com/ammaraskar/sphinx-action-test\n\n## Advanced Usage\n\nIf you wish to customize the command used to build the docs (defaults to\n`make html`), you can provide a `build-command` in the `with` block. For\nexample, to invoke sphinx-build directly you can use:\n\n```yaml\n    - uses: ammaraskar/sphinx-action@master\n      with:\n        docs-folder: \"docs/\"\n        build-command: \"sphinx-build -b html . _build\"\n```\n\nIf there's system level dependencies that need to be installed for your\nbuild, you can use the `pre-build-command` argument like so:\n\n```yaml\n    - uses: ammaraskar/sphinx-action@master\n      with:\n        docs-folder: \"docs2/\"\n        pre-build-command: \"apt-get update -y \u0026\u0026 apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended\"\n        build-command: \"make latexpdf\"\n```\n\n## Running the tests\n\n`python -m unittest`\n\n## Formatting\n\nPlease use [black](https://github.com/psf/black) for formatting:\n\n`black entrypoint.py sphinx_action tests`\n","funding_links":[],"categories":["Python"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fammaraskar%2Fsphinx-action","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fammaraskar%2Fsphinx-action","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fammaraskar%2Fsphinx-action/lists"}