diff --git a/.github/rtd-conf.py b/.github/rtd-conf.py new file mode 100644 index 00000000..e9aa41cf --- /dev/null +++ b/.github/rtd-conf.py @@ -0,0 +1,206 @@ + + +########################################################################### +# auto-created readthedocs.org specific configuration # +########################################################################### + + +# +# The following code was added during an automated build on readthedocs.org +# It is auto created and injected for every build. The result is based on the +# conf.py.tmpl file found in the readthedocs.org codebase: +# https://github.com/rtfd/readthedocs.org/blob/main/readthedocs/doc_builder/templates/doc_builder/conf.py.tmpl +# +# Note: this file shouldn't rely on extra dependencies. + +import importlib +import sys +import os.path + +# Borrowed from six. +PY3 = sys.version_info[0] == 3 +string_types = str if PY3 else basestring + +from sphinx import version_info + +# Get suffix for proper linking to GitHub +# This is deprecated in Sphinx 1.3+, +# as each page can have its own suffix +if globals().get('source_suffix', False): + if isinstance(source_suffix, string_types): + SUFFIX = source_suffix + elif isinstance(source_suffix, (list, tuple)): + # Sphinx >= 1.3 supports list/tuple to define multiple suffixes + SUFFIX = source_suffix[0] + elif isinstance(source_suffix, dict): + # Sphinx >= 1.8 supports a mapping dictionary for multiple suffixes + SUFFIX = list(source_suffix.keys())[0] # make a ``list()`` for py2/py3 compatibility + else: + # default to .rst + SUFFIX = '.rst' +else: + SUFFIX = '.rst' + +# Add RTD Static Path. Add to the end because it overwrites previous files. +if not 'html_static_path' in globals(): + html_static_path = [] +if os.path.exists('_static'): + html_static_path.append('_static') + +# Add RTD Theme only if they aren't overriding it already +using_rtd_theme = ( + ( + 'html_theme' in globals() and + html_theme in ['default'] and + # Allow people to bail with a hack of having an html_style + 'html_style' not in globals() + ) or 'html_theme' not in globals() +) +if using_rtd_theme: + html_theme = 'sphinx_rtd_theme' + html_style = None + html_theme_options = {} + + +# This following legacy behavior will gradually be sliced out until its deprecated and removed. +# Skipped for Sphinx 6+ +# Skipped by internal Feature flag SKIP_SPHINX_HTML_THEME_PATH +# Skipped by all new projects since SKIP_SPHINX_HTML_THEME_PATH's introduction (jan 2023) +if ( + using_rtd_theme + and version_info < (6,0) + and not False + ): + theme = importlib.import_module('sphinx_rtd_theme') + if 'html_theme_path' in globals(): + html_theme_path.append(theme.get_html_theme_path()) + else: + html_theme_path = [theme.get_html_theme_path()] + +# Define websupport2_base_url and websupport2_static_url +if globals().get('websupport2_base_url', False): + websupport2_base_url = 'https://readthedocs.org/websupport' + websupport2_static_url = 'https://assets.readthedocs.org/static/' + + +#Add project information to the template context. +context = { + 'using_theme': using_rtd_theme, + 'html_theme': html_theme, + 'current_version': "pre-release", + 'version_slug': "pre-release", + 'MEDIA_URL': "https://media.readthedocs.org/", + 'STATIC_URL': "https://assets.readthedocs.org/static/", + 'PRODUCTION_DOMAIN': "readthedocs.org", + 'proxied_static_path': "/_/static/", + 'versions': [ + ("latest", "/en/latest/"), + ("pre-release", "/en/pre-release/"), + ], + 'downloads': [ + ("html", "//docs.zammad.org/_/downloads/en/pre-release/htmlzip/"), + ("epub", "//docs.zammad.org/_/downloads/en/pre-release/epub/"), + ], + 'subprojects': [ + ], + 'slug': 'zammad', + 'name': u'zammad-documentation', + 'rtd_language': u'en', + 'programming_language': u'ruby', + 'canonical_url': '', + 'analytics_code': 'None', + 'single_version': False, + 'conf_py_path': '/', + 'api_host': 'https://readthedocs.org', + 'github_user': 'zammad', + 'proxied_api_host': '/_', + 'github_repo': 'zammad-documentation', + 'github_version': 'pre-release', + 'display_github': True, + 'bitbucket_user': 'None', + 'bitbucket_repo': 'None', + 'bitbucket_version': 'pre-release', + 'display_bitbucket': False, + 'gitlab_user': 'None', + 'gitlab_repo': 'None', + 'gitlab_version': 'pre-release', + 'display_gitlab': False, + 'READTHEDOCS': True, + 'using_theme': (html_theme == "default"), + 'new_theme': (html_theme == "sphinx_rtd_theme"), + 'source_suffix': SUFFIX, + 'ad_free': False, + 'docsearch_disabled': False, + 'user_analytics_code': '', + 'global_analytics_code': 'UA-17997319-1', + 'commit': 'f587f470', +} + +# For sphinx >=1.8 we can use html_baseurl to set the canonical URL. +# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl +if version_info >= (1, 8): + if not globals().get('html_baseurl'): + html_baseurl = context['canonical_url'] + context['canonical_url'] = None + + + + + +if 'html_context' in globals(): + for key in context: + if key not in html_context: + html_context[key] = context[key] +else: + html_context = context + +# Add custom RTD extension +if 'extensions' in globals(): + # Insert at the beginning because it can interfere + # with other extensions. + # See https://github.com/rtfd/readthedocs.org/pull/4054 + extensions.insert(0, "readthedocs_ext.readthedocs") +else: + extensions = ["readthedocs_ext.readthedocs"] + +# Add External version warning banner to the external version documentation +if 'branch' == 'external': + extensions.insert(1, "readthedocs_ext.external_version_warning") + readthedocs_vcs_url = 'None' + readthedocs_build_url = 'https://readthedocs.org/projects/zammad/builds/21493455/' + +project_language = 'en' + +# User's Sphinx configurations +language_user = globals().get('language', None) +latex_engine_user = globals().get('latex_engine', None) +latex_elements_user = globals().get('latex_elements', None) + +# Remove this once xindy gets installed in Docker image and XINDYOPS +# env variable is supported +# https://github.com/rtfd/readthedocs-docker-images/pull/98 +latex_use_xindy = False + +chinese = any([ + language_user in ('zh_CN', 'zh_TW'), + project_language in ('zh_CN', 'zh_TW'), +]) + +japanese = any([ + language_user == 'ja', + project_language == 'ja', +]) + +if chinese: + latex_engine = latex_engine_user or 'xelatex' + + latex_elements_rtd = { + 'preamble': '\\usepackage[UTF8]{ctex}\n', + } + latex_elements = latex_elements_user or latex_elements_rtd +elif japanese: + latex_engine = latex_engine_user or 'platex' + +# Make sure our build directory is always excluded +exclude_patterns = globals().get('exclude_patterns', []) +exclude_patterns.extend(['_build']) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 7ef4f4f6..bc50cc52 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -19,7 +19,7 @@ on: python_version: description: The version of Python binary to use. required: false - default: '3.7' + default: '3.11' type: string requirements_path: description: Path to the `requirements.txt`, relative to the repository root. @@ -52,7 +52,7 @@ jobs: shell: bash -eux {0} run: | python -m pip install --upgrade --no-cache-dir pip setuptools - python -m pip install --upgrade --no-cache-dir pillow mock==1.0.1 'alabaster>=0.7,<0.8,!=0.7.5' commonmark==0.9.1 recommonmark==0.5.0 'sphinx<2' 'sphinx-rtd-theme<0.5' 'readthedocs-sphinx-ext<2.3' 'jinja2<3.1.0' + python -m pip install --upgrade --no-cache-dir pillow mock==1.0.1 'alabaster>=0.7,<0.8,!=0.7.5' commonmark==0.9.1 recommonmark==0.5.0 sphinx sphinx-rtd-theme 'readthedocs-sphinx-ext<2.3' python -m pip install --exists-action=w --no-cache-dir -r ${{ inputs.requirements_path }} - name: Check RST Syntax @@ -61,27 +61,45 @@ jobs: python -m pip install --upgrade --no-cache-dir 'rstcheck[sphinx]' rstcheck --warn-unknown-settings --recursive . + # Runs only on Pull Requests and if they contain changes. + - name: Check for Outstanding Code Comments + if: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha != github.sha }} + shell: bash -eux {0} + env: + BASE_SHA: ${{ github.event.pull_request.base.sha }} + COMMENT_KEYWORD: ${{ format('{0}{1}{2}{3}', 'T', 'O', 'D', 'O') }} # HA! + run: | + COMMENTS=$(git diff $BASE_SHA... --color=always | perl -wlne 'print $1 if /^\e\[32m\+\e\[m\e\[32m(.*)\e\[m$/' | grep $COMMENT_KEYWORD || true) + if [ -n "$COMMENTS" ]; then + echo "::warning title=New $COMMENT_KEYWORD comments found!::Found $COMMENT_KEYWORD comments, please check if this was intentional or not..." + echo "$COMMENTS" + fi + - name: Check Translation Sources shell: bash -eux {0} run: | if [[ -d "locale" ]]; then make gettext if git status --short | grep " M locale/"; then - echo "Translation sources are out-of-date, please update them with `make gettext`." + echo "::error title=Translation sources are out-of-date!::Please update translation sources with 'make gettext' command..." exit 1 fi fi - - name: Debug Configuration + - name: Modify Configuration shell: bash -eux {0} - run: cat conf.py + run: | + test -f .github/rtd-conf.py + cat .github/rtd-conf.py >> ${{ inputs.docs_path }}/conf.py + cat ${{ inputs.docs_path }}/conf.py - name: Build Documentation shell: bash -eux {0} run: | cd ${{ inputs.docs_path }} - python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html - python -m sphinx -T -E -b epub -d _build/doctrees -D language=en . _build/epub + python -m sphinx -T -E -W --keep-going -b html -d _build/doctrees -D language=en . _build/html + python -m sphinx -T -E -W --keep-going -b readthedocssinglehtmllocalmedia -d _build/doctrees -D language=en . _build/htmlzip + python -m sphinx -T -E -W --keep-going -b epub -d _build/doctrees -D language=en . _build/epub - name: Compute short SHA id: sha @@ -93,6 +111,12 @@ jobs: name: html-${{ steps.sha.outputs.sha_short }} path: ${{ inputs.docs_path }}/_build/html/ + - name: Upload htmlzip Artifact + uses: actions/upload-artifact@v3 + with: + name: htmlzip-${{ steps.sha.outputs.sha_short }} + path: ${{ inputs.docs_path }}/_build/htmlzip/ + - name: Upload epub Artifact uses: actions/upload-artifact@v3 with: diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..8f09f88e --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,23 @@ +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +version: 2 + +build: + os: ubuntu-22.04 + apt_packages: + - gettext + tools: + python: '3.11' + +sphinx: + configuration: conf.py + fail_on_warning: true + +formats: + - htmlzip + - epub + +python: + install: + - requirements: requirements.txt diff --git a/conf.py b/conf.py index d945aba5..02668ff1 100644 --- a/conf.py +++ b/conf.py @@ -24,6 +24,10 @@ html_theme = "sphinx_rtd_theme" html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] +# Suppress "WARNING: unknown mimetype for ..." during EPUB builds. +# https://github.com/sphinx-doc/sphinx/issues/3214 +suppress_warnings = ['epub.unknown_project_files'] + # thanks to https://blog.deimos.fr/2014/10/02/sphinxdoc-and-readthedocs-theme-tricks-2/ on_rtd = os.environ.get('READTHEDOCS', None) == 'True' @@ -53,16 +57,20 @@ def setup(app): ] # Get current version we're on for possible version warning - version = os.environ.get('READTHEDOCS_VERSION') + rtd_version = os.environ.get('READTHEDOCS_VERSION') # If we're **not on latest**, we'll display a deprecation warning. - if version == 'latest': - branch = version - elif version == 'pre-release': + if rtd_version == 'latest': + branch = rtd_version + elif rtd_version == 'pre-release': branch = "pre-release" else: branch = "old-version" +# Ensure `version` config is set due to EPUB requirements: +# WARNING: conf value "version" should not be empty for EPUB3 +version = branch + # Default definitions for this documentations version warnings if applicable # https://sphinx-version-warning.readthedocs.io/en/latest/configuration.html versionwarning_project_slug = "zammad-documentation"