ammaraskar / sphinx-action Goto Github PK
View Code? Open in Web Editor NEWGithub action that builds docs using sphinx and places errors inline
License: Apache License 2.0
Github action that builds docs using sphinx and places errors inline
License: Apache License 2.0
AFAICT, only make html
is called, is it possible to create PDF output, too?
I guess you would need a Docker image with LaTeX installed ...
I have used https://github.com/dante-ev/docker-texlive on CircleCI and it worked great, but probably there is a better suited image?
I just found, that not all warnings issued by sphinx are output as GitHub annotations. A current example would be this warning that is clearly readable in the output of the sphinx run but that is not propagated to the list of annotations (see e.g. here).
This might be due to the fact that these missing warnings are within translations, thus Sphinx adds a <translated>:1
in the file name/line number output. Is there potentially a regex involved that fails to trigger here?
I'm testing the sphinx-action and I noticed that if a there is non-existing document added to toctree, then annotation is missing.
First, the problem toctree contains reference to nonexisting document 'drivers'
is listed:
Next, I click on Check warning on line 7 in project/doc/index.rst
and it gets me to here:
As you can see, there is only the annotation for the Unknown directive type "whoops"
issue, but none for the toctree contains reference to nonexisting document 'drivers'
I use autodoc for one of my packages that imports psutil
which pip
will try to build natively using gcc
. The build fails, though, with the error: gcc: command not found
. I'm not sure how you'd detect that at runtime, but a possible solution is just including an entire C compiler in the image. Which I know isn't ideal, but psutil
is pretty widely used, so I think it's a common use-case.
This is a feature request:
Add output
key in action.yml
which contains the number of warning generated while doing the build.
It would help in taking decisions for other steps
in GitHub workflow.
Hi @ammaraskar thanks for this action!
We've noticed that our sphinx build CI has stopped working since the release of sphinx 4.1.0.
Our action is here: https://github.com/PyTorchLightning/pytorch-lightning/blob/e5732a11583572f13c68c02cf50a26fd9863229a/.github/workflows/docs-checks.yml#L11
The error we are getting is:
Could not import extension sphinx.builders.epub3 (exception: cannot import name 'RemovedInSphinx40Warning' from 'sphinx.deprecation' (/usr/local/lib/python3.8/site-packages/sphinx/deprecation.py))
You can see the failing CI here:
https://github.com/PyTorchLightning/pytorch-lightning/pull/7960/checks?check_run_id=3044973574#step:4:435
I'm not sure what the cause of the error is so any help you can give us would be awesome. Thanks π
Hi, my GitHub Action Sphinx doc generation started failing with Sphinx 4.1.0 (It has been working with previous Sphinx 4.0.2).
The errors I got are:
...
Running Sphinx v4.1.0
Extension error:
Could not import extension sphinx.builders.epub3 (exception: cannot import name 'RemovedInSphinx40Warning' from 'sphinx.deprecation' (/usr/local/lib/python3.8/site-packages/sphinx/deprecation.py))
make: *** [Makefile:20: html] Error 2
...
When I create a sphinx doc locally it builds as expected, but sphinx-action creates an empty doc. It must have to do with the sphinx-action not finding the target python modules as specified in conf.py
.
Any ideas to configure the sphinx-action or conf.py
correctly?
When I build the sphinx doc locally on my machine via cd docs/ && make html
the resulting html looks as expected
My .github/workflows/sphinx_action.yml
includes
steps:
# Checkout repo
- uses: actions/checkout@v2
# Build sphinx doc
- uses: ammaraskar/sphinx-action@master
with:
docs-folder: "docs/"
and generates an empty skeleton of a Sphinx Doc
.
βββ docs
βΒ Β βββ conf.py
βΒ Β βββ index.rst
βΒ Β βββ make.bat
βΒ Β βββ Makefile
βΒ Β βββ requirements.txt
βΒ Β βββ sync.log
βββ .github
βΒ Β βββ workflows
βΒ Β βββ sphinx_action.yml
βββ .gitignore
βββ mypackage
βΒ Β βββ __init__.py
βΒ Β βββ subfolder
βΒ Β βΒ Β βββ __init__.py
βΒ Β βΒ Β βββ subclass.py
βΒ Β βββ superclass.py
βββ Pipfile
βββ Pipfile.lock
βββ README.md
conf.py
ConfigurationMy docs/conf.py
looks as follows. (Mind that I added three entries to the sys.path
manually in order to make Sphinx find all python modules.)
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
from m2r import MdInclude
sys.path.insert(0, os.path.abspath('..'))
sys.path.insert(0, os.path.abspath('../mypackage'))
sys.path.insert(0, os.path.abspath('../mypackage/subfolder'))
# -- Project information -----------------------------------------------------
project = 'MyPackage'
copyright = ''
author = 'Testuser'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx.ext.autodoc',
'recommonmark'
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
#
source_suffix = ['.rst', '.md']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# document the init of a class, too
autoclass_content = 'both'
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'nature'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# from m2r to make `mdinclude` work
def setup(app):
config = {
# 'url_resolver': lambda url: github_doc_root + url,
'auto_toc_tree_section': 'Contents',
'enable_eval_rst': True,
}
# from m2r to make `mdinclude` work
app.add_config_value('no_underscore_emphasis', False, 'env')
app.add_config_value('m2r_parse_relative_links', False, 'env')
app.add_config_value('m2r_anonymous_references', False, 'env')
app.add_config_value('m2r_disable_inline_math', False, 'env')
app.add_directive('mdinclude', MdInclude)
[[source]]
verify_ssl = true
url = "https://pypi.org/simple"
name = "pypi"
[dev-packages]
[packages]
m2r = {index = "pypi",version = "==0.2.1"}
pandas = {index = "pypi",version = "==1.0.3"}
sphinx = {index = "pypi",version = "==3.1.0"}
recommonmark = {index = "pypi",version = "==0.6.0"}
mypackage = "*"
[requires]
python_version = "3.8"
Note: I asked the same question on SO.
I've been using your action for a while now with no problems but I'm now getting build errors consistently. The action seems to run the Sphinx build with Python 3.10 and fails with the traceback below.
I've set up a build matrix to run specific Python versions, with 3.10 an allowed failure, but it continues to use Python 3.10 in each environment. What's the recommended way to tell the action to use a specific version of Python?
ERROR: Command errored out with exit status 1: /usr/local/bin/python -u -c 'import io, os, sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-req-build-pfh4xj24/setup.py'"'"'; __file__='"'"'/tmp/pip-req-build-pfh4xj24/setup.py'"'"';f = getattr(tokenize, '"'"'open'"'"', open)(__file__) if os.path.exists(__file__) else io.StringIO('"'"'from setuptools import setup; setup()'"'"');code = f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' install --record /tmp/pip-record-aw7cgm0a/install-record.txt --single-version-externally-managed --compile --install-headers /usr/local/include/python3.10/sdss-datamodel Check the logs for full command output.
WARNING: You are using pip version 21.2.4; however, version 21.3.1 is available.
You should consider upgrading via the '/usr/local/bin/python -m pip install --upgrade pip' command.
Traceback (most recent call last):
File "/usr/local/lib/python3.10/runpy.py", line 196, in _run_module_as_main
return _run_code(code, main_globals, None,
File "/usr/local/lib/python3.10/runpy.py", line 86, in _run_code
exec(code, run_globals)
File "/usr/local/lib/python3.10/site-packages/sphinx/__main__.py", line 13, in <module>
from sphinx.cmd.build import main
File "/usr/local/lib/python3.10/site-packages/sphinx/cmd/build.py", line 25, in <module>
from sphinx.application import Sphinx
File "/usr/local/lib/python3.10/site-packages/sphinx/application.py", line 32, in <module>
from sphinx.config import Config
File "/usr/local/lib/python3.10/site-packages/sphinx/config.py", line 23, in <module>
from sphinx.util import logging
File "/usr/local/lib/python3.10/site-packages/sphinx/util/__init__.py", line 35, in <module>
from sphinx.util import smartypants # noqa
File "/usr/local/lib/python3.10/site-packages/sphinx/util/smartypants.py", line 33, in <module>
from sphinx.util.docutils import __version_info__ as docutils_version
File "/usr/local/lib/python3.10/site-packages/sphinx/util/docutils.py", line 31, in <module>
from sphinx.util.typing import RoleFunction
File "/usr/local/lib/python3.10/site-packages/sphinx/util/typing.py", line 34, in <module>
from types import Union as types_Union
ImportError: cannot import name 'Union' from 'types' (/usr/local/lib/python3.10/types.py)
make: *** [Makefile:20: html] Error 1
[sphinx-action] Starting sphinx-action build.
Traceback (most recent call last):
File "/entrypoint.py", line 22, in <module>
Running: apt-get update -y && apt-get install -y gcc && pip install .[docs]
====================================
Building docs in docs/sphinx/
====================================
action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
File "/sphinx_action/action.py", line 152, in build_all_docs
return_code, annotations = build_docs(github_env.build_command, docs_dir)
File "/sphinx_action/action.py", line 134, in build_docs
with open(log_file, "r") as f:
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/sphinx-log'
[sphinx-action] Running: ['make', 'html', '-e']
I tried
- name: Sphinx Build
uses: ammaraskar/sphinx-action@master
with:
docs-folder: "source/"
pre-build-command: "apt-get update -y && mkdir -p /usr/share/man/man1 && apt-get install -y plantuml"
build-command: "PLANTUML_JAR=/usr/share/plantuml/plantuml.jar && sphinx-build -b html . _build"
or
pre-build-command: "export apt-get update -y && mkdir -p /usr/share/man/man1 && apt-get install -y plantuml"
or
build-command: "export PLANTUML_JAR=/usr/share/plantuml/plantuml.jar && sphinx-build -b html . _build"
I use in conf.py like:
plantuml = "java -DPLANTUML_LIMIT_SIZE=24384 -jar "+ os.environ.get("PLANTUML_JAR")
Since plantuml use java, What should i do to use plantuml file.
I tried this:
- name: Sphinx Build
uses: ammaraskar/sphinx-action@master
with:
docs-folder: "source/"
pre-build-command: "apt-get update -y && apt-get install -y openjdk-8-jdk"
build-command: "java -version && sphinx-build -b html . _build"
I failed show this:
FileNotFoundError: [Errno 2] No such file or directory: 'java'
Is Any one has any suggestion?
Hi all,
This action used to work but recently (after an Ubuntu update?) I got the following error (more at
https://github.com/tbarbette/npf-docs/actions/runs/8567891792/job/23480593613)
AttributeError: module 'docutils.nodes' has no attribute 'meta'
make: *** [Makefile:20: html] Error 1
[sphinx-action] Starting sphinx-action build.
Running:
Hi @ammaraskar,
Would you consider moving this repo to @sphinx-doc? I'd like to provide first-party support for a GitHub Actions action, and it makes sense to build on prior art.
If not, no worries, but I thought worth asking!
Thanks,
Adam
I'm just getting into Sphinx so please forgive any ignorance... We're working on automating updates to a User Guide compiled with Sphinx (see e.g. codeigniter4/CodeIgniter4#2671 (comment)) and I was wondering if there's a hold up for switching the Action definition to use pip3
in support of Python 3 and the latest Sphinx versions?
This syntax is causing the action to fail. The syntax is for python3.10.
# file.py
with (
open(...) as f, # this is line 119
open(...) as g,
):
do_cool_stuff()
error message:
[AutoAPI] Reading files... [ 26%] /github/workspace/.../file.py
Extension error (autoapi.extension):
Handler <function run_autoapi at 0x7f0ef2a43af0> for event 'builder-inited' threw an exception (exception: Parsing Python code failed:
invalid syntax (<unknown>, line 119))
make: *** [Makefile:20: html] Error 2
[sphinx-action] Starting sphinx-action build.
Running:
====================================
Building docs in docs/
====================================
[sphinx-action] Running: ['make', 'html', '-e']
[sphinx-action] Build failed with 0 warnings
Traceback (most recent call last):
File "/entrypoint.py", line 22, in <module>
action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
File "/sphinx_action/action.py", line 167, in build_all_docs
raise RuntimeError("Build failed")
RuntimeError: Build failed
our action file:
name: Sphinx build
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Build HTML
uses: ammaraskar/[email protected] # uses the /docs/requirements.txt file
Hi, may I ask how to define a custom path to extra requirements, e.g in our case it is requirements/docs.txt
for now, the action is failing for missing dependencies
https://github.com/PyTorchLightning/pytorch-lightning/pull/2128/checks?check_run_id=753522640
for example, RTD config has
install:
- requirements: requirements/docs.txt
I created a PAT and entered it into a secret. However, the action is failing with an authentication error. Do you have more detailed documentation to work on a private repo?
I ran into some trouble using sphinx-action to include class documentations. The documentation part is inside the class/function definitions inside the package code.
Local build by using sphinx make html
But when i build the documentation by the provided package, the result is the following:
According to this answer, i want to include the package as given.
https://stackoverflow.com/questions/73033594/github-action-using-wrong-version-of-python
So i added the -e .
option in the requirements.txt file for this github action.
The the package to install requires minimum python 3.10.
By using setup-python
, the version is pinned to 3.10
.
The first run pip install -e .
works perfect using python 3.10.
When coming to the Build HTML
section, with the -e .
option, the following error appears.
ERROR: Package 'femmt' requires a different Python: 3.8.2 not in '>=3.10'
It seems like, for this package is python 3.8
used. It is not clear for me, why?
When i remove the -e .
option inside the requirements.txt
, the documentation is bild without the class description as shown as in the second figure.
Do you have any ideas how to use python 3.10 for the build process?
Or are there any other ways to overcome this drawback?
here is the build file:
jobs:
build:
runs-on: ubuntu-latest
permissions:
contents: write
steps:
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: '3.10'
- uses: actions/checkout@v4
- name: Install sphinx and build documentation with sphinx
run: |
python --version
pip install sphinx sphinx-multiversion sphinx_rtd_theme sphinxcontrib-email
pip install -e .
- name: Build HTML
uses: ammaraskar/sphinx-action@master
with:
docs-folder: "docs/"
I've just tried sphinx-action
and got this error:
Traceback (most recent call last):
File "/entrypoint.py", line 22, in <module>
action.build_all_docs(github_env, sys.argv[1:])
File "/sphinx_action/action.py", line 124, in build_all_docs
return_code, annotations = build_docs(docs_dir)
File "/sphinx_action/action.py", line 99, in build_docs
with open(log_file, 'r') as f:
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/sphinx-log'
##[error]Docker run failed with exit code 1
It took me a while, but I found out that the real error is a few lines further up:
make: *** No rule to make target 'html'. Stop.
I'm not using a Makefile
in my project (because I don't like it, see e.g. sphinx-doc/sphinx#5618).
It would be great to support workflows without Makefile
.
For example, https://readthedocs.org/ doesn't require having a Makefile
; they somehow automagically find a conf.py
and start Sphinx from there, without needing a Makefile
.
This is a feature request.
Which will convert warning into error and fail the build on error.
I have tried in various ways to support it but the function which reads the log file to generate warning
for github actions always fails.
One such approach was:
build-command: make html -W
This stems from an old issue where jinja2
imports were deprecated.
PR #47, which updates the Docker image to use sphinx 5.0.2
should resolve this for at least python <3.10
(see astropy/astropy
Issue #11725).
I'm using nbsphinx which uses pandoc. My docs always failed to build because pandoc was never found, I tried installing it using several methods:
apt-install
before using this actionBoth methods failed, I guess the first one failed because it did not created a pandoc shortcut for the system, and the second failed because this actions uses a custom Docker file?
Any tips on how should I install pandoc?
Trying to install additional packages, running apt update --yes
fails with an error (presumably something to do with the new debian release?)
Config:
with:
docs-folder: docs/
pre-build-command: apt update --yes && apt install --yes git build-essential pandoc
Log:
Get:1 http://deb.debian.org/debian buster InRelease [122 kB]
Get:2 http://security.debian.org/debian-security buster/updates InRelease [65.4 kB]
Get:3 http://deb.debian.org/debian buster-updates InRelease [51.9 kB]
Reading package lists...
E: Repository 'http://deb.debian.org/debian buster InRelease' changed its 'Suite' value from 'stable' to 'oldstable'
E: Repository 'http://deb.debian.org/debian buster-updates InRelease' changed its 'Suite' value from 'stable-updates' to 'oldstable-updates'
E: Repository 'http://security.debian.org/debian-security buster/updates InRelease' changed its 'Suite' value from 'stable' to 'oldstable'
Link to a build:
https://github.com/cta-observatory/ctapipe/pull/1774/checks?check_run_id=3424315763
Hello and thanx for this nice tool.
I wanted to add it our project, but it fails with a message I don't know how to interpret... I have added the example to workflows and open PR which triggers the action job and then I got this error:
/usr/bin/docker run --name e87b527fc098e2c9b441b99e634ffe3814c665_f9dce4 --label e87b52 --workdir /github/workspace --rm -e INPUT_DOCS-FOLDER -e INPUT_REPO-TOKEN -e INPUT_BUILD-COMMAND -e INPUT_PRE-BUILD-COMMAND -e HOME -e GITHUB_REF -e GITHUB_SHA -e GITHUB_REPOSITORY -e GITHUB_RUN_ID -e GITHUB_RUN_NUMBER -e GITHUB_ACTOR -e GITHUB_WORKFLOW -e GITHUB_HEAD_REF -e GITHUB_BASE_REF -e GITHUB_EVENT_NAME -e GITHUB_WORKSPACE -e GITHUB_ACTION -e GITHUB_EVENT_PATH -e RUNNER_OS -e RUNNER_TOOL_CACHE -e RUNNER_TEMP -e RUNNER_WORKSPACE -e ACTIONS_RUNTIME_URL -e ACTIONS_RUNTIME_TOKEN -e GITHUB_ACTIONS=true -v "/var/run/docker.sock":"/var/run/docker.sock" -v "/home/runner/work/_temp/_github_home":"/github/home" -v "/home/runner/work/_temp/_github_workflow":"/github/workflow" -v "/home/runner/work/pytorch-lightning/pytorch-lightning":"/github/workspace" e87b52:7fc098e2c9b441b99e634ffe3814c665
Running:
{'message': 'Resource not accessible by integration', 'documentation_url': 'https://developer.github.com/v3/checks/runs/#create-a-check-run'}
Traceback (most recent call last):
File "/entrypoint.py", line 27, in <module>
action.build_all_docs(github_env, [os.environ.get('INPUT_DOCS-FOLDER')])
File "/sphinx_action/action.py", line 125, in build_all_docs
status_id = status_check.create_in_progress_status_check(
File "/sphinx_action/status_check.py", line 64, in create_in_progress_status_check
r.raise_for_status()
File "/usr/local/lib/python3.8/site-packages/requests/models.py", line 940, in raise_for_status
raise HTTPError(http_error_msg, response=self)
requests.exceptions.HTTPError: 403 Client Error: Forbidden for url: https://api.github.com/repos/PyTorchLightning/pytorch-lightning/check-runs
What I am doing wrong?
The latex build action
- name: Build PDF docs
uses: ammaraskar/sphinx-action@master
with:
docs-folder: "docs/"
pre-build-command: "apt-get update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended"
build-command: "make latexpdf"
was previously running correctly, but has (today) started failing with the error:
make[1]: latexmk: Command not found
Here's links to the relevant files:
For the repo in question, no documentation changes or changes to the documentation workflow have occurred between the last successful run 6 days ago and the recent failing build. I note that no commits have been made to ammaraskar/sphinx-action in the past 6 days. And the sphinxdoc base docker image has not been changed.
I'm at a loss to understand what is causing this problem.
In our project we also build translated version of the documentation, currently we can't test this with your action.
The command we use is: sphinx-intl build --locale-dir=docs/locale/
We can install sphinx-intl
no problem (by adding it in the requirements.txt
), but with the custom build-command
we can't execute because some default arguments are added to any command which in this can makes sphinx-intl
fail.
It would be nice if we somehow could build the international documentation.
Hope you can offer a solution
Version: 0.1
The build fails because it cannot find some sphinx log file. There is no indication anywhere how it should be created?
The RTD containers have multiple versions of Python and e.g. all of LaTeX installed:
https://hub.docker.com/r/readthedocs/build/
An excerpted Dockerfile and Makefile for building docs with the ReadTheDocs container:
https://gist.github.com/westurner/9827e4d2665d08832ad37343085721d3
I am writing a Python package. The code documentation should be realized via a workflow on a Github page. I have the following folder structure:
D:.
β .gitignore
β .pylintrc
β LICENSE
β README.md
β requirements.txt
β setup.py
β
ββββ.github
β ββββworkflows
β pylint.yml
β pypi.yml
β sphinx.yml
β
ββββdocs
β conf.py
β
ββββriffecx
__init__.py
__main__.py
The Python source code works and even the linter works. All other workflows also run without problems.
Here is my Sphinx workflow as sphinx.yml
name: "Pull Request Docs Check"
on:
- push
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v1
- name: make folder
run: |
mkdir /tmp/sphinx-log
- uses: ammaraskar/sphinx-action@master
with:
docs-folder: "docs/"
The source code for the workflow is from the github action page. I have changed the pull_request to a push, because it should run again after each push. GitHub Sphinx Action
Here I put the error log of the workflow. Error:
make: *** No rule to make target 'html'. Stop.
[sphinx-action] Starting sphinx-action build.
Running:
====================================
Building docs in docs/
====================================
Traceback (most recent call last):
[sphinx-action] Running: ['make', 'html', '-e']
File "/entrypoint.py", line 22, in <module>
action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
File "/sphinx_action/action.py", line 152, in build_all_docs
return_code, annotations = build_docs(github_env.build_command, docs_dir)
File "/sphinx_action/action.py", line 134, in build_docs
with open(log_file, "r") as f:
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/sphinx-log'
Example: https://github.com/Riffecs/riffecx/runs/6498919334?check_suite_focus=true
Unfortunately, I have a complete error in thinking somewhere. So I thought that I get the sphinx files either as a branch or as an artifact and from there I can "upload" them to the github page. But obviously I think wrong there. can you help me there?
Thank you.
Dear Authors,
I am quite naive about Github Action. What I want to do is to create the HTML documents from a public repository.
Let say, I want to create the HTML documents from NumPy. How could I do that?
Here is my naive script, it doesn't work. It would be great if you help me to point it out.
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@master
with:
repository: numpy/numpy
path: .
- uses: ammaraskar/sphinx-action@master
with:
build-command: "sphinx-build -b html . _build"
docs-folder: "doc/"
Thank you.
Thanks for the nice action! I was wondering though, can I also fail my build on sphinx errors and warnings?
I have tried replacing the custom build command with:
- name: Build docs using action
uses: ammaraskar/sphinx-action@master
with:
docs-folder: "docs/source/"
build-command: "pip install sphinx-multiversion && sphinx-multiversion . docs/_build"
but it seems it is not possible to use this action with sphinx-multiversion yet, would it be possible to support such feature?
I get the warning:
WARNING: autodoc: failed to import module 'xxxxx' from module 'src.xxxx'; the following exception was raised:
libtk8.6.so: cannot open shared object file: No such file or directory link
I try to generate documentation from docstrings using the extensions = ['sphinx.ext.autodoc',] in the conf.py
These modules import tkinter
which seems to trigger the above mentioned warnings.
It does not raise an error but the documetantion is not built in index.rst
People say: All you need to do is to install the tkinter package
I have tried to do so both for the requirements.txt and sudo apt-get install tk
gh-pages
branch./docs/_build/latex/REPO-NAME.pdf
if latex was built.When I run this in a github action I get this error:
====================================
Building docs in docs/
====================================
[sphinx-action] Running: ['sphinx-build', '-b', 'html', '.', '_build', '--keep-going', '--no-color', '-w', '/tmp/sphinx-log']
action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
File "/sphinx_action/action.py", line 152, in build_all_docs
return_code, annotations = build_docs(github_env.build_command, docs_dir)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/sphinx_action/action.py", line 134, in build_docs
with open(log_file, "r") as f:
^^^^^^^^^^^^^^^^^^^
FileNotFoundError: [Errno 2] No such file or directory: '/tmp/sphinx-log'
Looks like the script assumes that there will be a logfile in /tmp
and when that is not true, then we get an error. I can't actually tell if this is a side-effect of build_all_docs
failing, or if it succeeded, but the log can't be parsed.
Perhaps the right fix is to check to make sure the log_file is written before reading it. If it's not written, then inspect the return_code
and emit a result based on that, together with mention of failure writing the logfile?
@ammaraskar thank you for your work.
I am trying to use this action but my makefile uses sphinx-intl and even though the package is installed during the dependencies install, it fails during make:
https://github.com/SrNetoChan/QGIS-Documentation/pull/3/checks?check_run_id=366090523
I would appreciate your help.
thanks!!
Great Action! Could you please put out a new minor version with Sphinx 3.x?
I've been getting an error using a requirements.txt file that contains a -e
flagged git package. I think (without investigating further) the problem is that subprocess.check_call()
here is executing the pip install, which tries to run git
, however the subprocess doesn't have PATH
so it fails to find it.
Obtaining pydicom from git+git://github.com/pydicom/pydicom.git#egg=pydicom (from -r docs/requirements.txt (line 10))
Cloning git://github.com/pydicom/pydicom.git to ./src/pydicom
ERROR: Error [Errno 2] No such file or directory: 'git' while executing command git clone -q git://github.com/pydicom/pydicom.git /github/workspace/src/pydicom
ERROR: Cannot find command 'git' - do you have 'git' installed and in your PATH?
requirements.txt
numpy
matplotlib
sphinx
pillow
sphinx_rtd_theme
numpydoc
sphinx-gallery
sphinxcontrib-napoleon
sphinx-issues~=1.0
-e git://github.com/pydicom/pydicom.git#egg=pydicom
First off, a wonderful Action!
sphinx_options appear to be hard-coded at
https://github.com/ammaraskar/sphinx-action/blob/master/sphinx_action/action.py#L110
Any chance they could be passed alongside build-command? (or have I missed something)
Thank you,
Don
My GitHub action includes following job:
- name: build pdf doc
uses: ammaraskar/sphinx-action@master
with:
pre-build-command: 'apt-get update -y && apt-get install -y latexmk texlive-latex-recommended texlive-latex-extra texlive-fonts-recommended'
build-command: 'make latexpdf'
docs-folder: 'doc'
Also see
Folder structure:
I get following error:
====================================
Building docs in doc
Traceback (most recent call last):
====================================
File "/entrypoint.py", line 22, in <module>
[sphinx-action] Running: ['make', 'latexpdf', '-e']
action.build_all_docs(github_env, [os.environ.get("INPUT_DOCS-FOLDER")])
[sphinx-action] Build failed with 0 warnings
File "/sphinx_action/action.py", line 167, in build_all_docs
raise RuntimeError("Build failed")
=> How to fix this?
Related:
While working on #39, I also noticed that the Sphinx team have a second container image, spinxdoc/sphinx-latexpdf which they maintain in parallel to sphinxdoc/sphinx
. The image is, as they caution, huge (2GB!), but the tradeoff is that it contains nearly all of the packages that users who run apt install <incredible amounts of texlive stuff>
will be downloading anyway, every time they use the action.
Presumably GitHub caches docker images, whereas the apt install into the container can't be cached, so using the image would seem like a more efficient way of using latexpdf for those who need it. It might be too heavy to use for every sphinx-action
run, but perhaps it could be offered as an alternate image?
I was thinking about how that could be done, and I think this would work (in action.yml
):
inputs:
# ...
latexpdf:
description:
Use a container with latexpdf and dependencies pre-installed
required: false
default: false
runs:
- using: 'docker'
if: ${{ inputs.latexpdf == false }}
image: 'Dockerfile'
- using: 'docker'
if: ${{ inputs.latexpdf == true }}
using 'Dockerfile.latexpdf'
If that doesn't fly, or is just too messy, then maybe even publishing a second action based on sphinx_action
, but using sphinxdoc/sphinx-latexpdf
, would be worth it?
I have some troublesome dependencies for my Python project where some of the wheels on PYPI are broken and pip install -r requirements.txt
does not work when building my docs. Is it possible to use Docker image in lieu of that pip install requirements.txt
?
Hi,
the action does not work with yasfb:
Extension error (yasfb):
Handler <function create_feed_item at 0x7fb4a8f2f9d0> for event 'html-page-context' threw an exception (exception: [Errno 2] No such file or directory: 'git')
In my sphinx conf.py
I call this command git describe --tags --abbrev=0
to get the current tag (that represents the version of the sphinx doc).
but I get an error: fatal: No names found, cannot describe anything.
how to I clone the repo? Is there a way to clone it with all the tags?
thanks
#56 added support for different Sphinx versions through tags. master
, however, still points to 2.4.4
. That was purposeful. It was done to not immediately breaks builds and give people time to kick the tires on the tagging approach.
This issue is for tracking/coming up with a sane policy for moving the the master
pointer to something more recent. Perhaps just a message in the logs encouraging folks to pin a specific version.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.