RomanNum3ral
/
scrapy
mirror of https://github.com/scrapy/scrapy.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore(docs): refactor config (#6623)

This commit is contained in:
Rotzbua 2025-01-20 12:18:30 +01:00 committed by GitHub
parent 8bc8f752e6
commit e0c828b7f6
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 65 additions and 270 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.readthedocs.yml
View File

@ -5,7 +5,7 @@ sphinx:
fail_on_warning: true fail_on_warning: true
build: build:
os: ubuntu-20.04 os: ubuntu-24.04
tools: tools:
# For available versions, see: # For available versions, see:
# https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python # https://docs.readthedocs.io/en/stable/config-file/v2.html#build-tools-python

104
docs/Makefile
View File

@ -1,96 +1,20 @@
# # Minimal makefile for Sphinx documentation
# Makefile for Scrapy documentation [based on Python documentation Makefile]
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# #
# You can set these variables from the command line. # You can set these variables from the command line, and also
PYTHON = python # from the environment for the first two.
SPHINXOPTS = SPHINXOPTS ?=
PAPER = SPHINXBUILD ?= sphinx-build
SOURCES = SOURCEDIR = .
SHELL = /usr/bin/env bash BUILDDIR = build
ALLSPHINXOPTS = -b $(BUILDER) -d build/doctrees \
-D latex_elements.papersize=$(PAPER) \
$(SPHINXOPTS) . build/$(BUILDER) $(SOURCES)
.PHONY: help update build html htmlhelp clean
# Put it first so that "make" without argument is like "make help".
help: help:
@echo "Please use \`make <target>' where <target> is one of" @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
@echo " html to make standalone HTML files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " text to make plain text files"
@echo " changes to make an overview over all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " watch build HTML docs, open in browser and watch for changes"
build-dirs: .PHONY: help Makefile
mkdir -p build/$(BUILDER) build/doctrees
build: build-dirs # Catch-all target: route all unknown targets to Sphinx using the new
sphinx-build $(ALLSPHINXOPTS) # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
@echo %: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
build-ignore-errors: build-dirs
-sphinx-build $(ALLSPHINXOPTS)
@echo
html: BUILDER = html
html: build
@echo "Build finished. The HTML pages are in build/html."
htmlhelp: BUILDER = htmlhelp
htmlhelp: build
@echo "Build finished; now you can run HTML Help Workshop with the" \
"build/htmlhelp/pydoc.hhp project file."
latex: BUILDER = latex
latex: build
@echo "Build finished; the LaTeX files are in build/latex."
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
"run these through (pdf)latex."
text: BUILDER = text
text: build
@echo "Build finished; the text files are in build/text."
changes: BUILDER = changes
changes: build
@echo "The overview file is in build/changes."
linkcheck: BUILDER = linkcheck
linkcheck: build
@echo "Link check complete; look for any errors in the above output " \
"or in build/$(BUILDER)/output.txt"
linkfix: BUILDER = linkcheck
linkfix: build-ignore-errors
$(PYTHON) utils/linkfix.py
@echo "Fixing redirecting links in docs has finished; check all " \
"replacements before committing them"
doctest: BUILDER = doctest
doctest: build
@echo "Testing of doctests in the sources finished, look at the " \
"results in build/doctest/output.txt"
pydoc-topics: BUILDER = pydoc-topics
pydoc-topics: build
@echo "Building finished; now copy build/pydoc-topics/pydoc_topics.py " \
"into the Lib/ directory"
coverage: BUILDER = coverage
coverage: build
htmlview: html
$(PYTHON) -c "import webbrowser; from pathlib import Path; \
webbrowser.open(Path('build/html/index.html').resolve().as_uri())"
clean:
-rm -rf build/*
watch: htmlview
watchmedo shell-command -p '*.rst' -c 'make html' -R -D

18
docs/_ext/scrapyfixautodoc.py Normal file
View File

@ -0,0 +1,18 @@
"""
Must be included after 'sphinx.ext.autodoc'. Fixes unwanted 'alias of' behavior.
https://github.com/sphinx-doc/sphinx/issues/4422
"""
# pylint: disable=import-error
from sphinx.application import Sphinx
def maybe_skip_member(app: Sphinx, what, name: str, obj, skip: bool, options) -> bool:
if not skip:
# autodocs was generating a text "alias of" for the following members
return name in {"default_item_class", "default_selector_class"}
return skip
def setup(app: Sphinx) -> None:
app.connect("autodoc-skip-member", maybe_skip_member)

211
docs/conf.py
View File

@ -1,17 +1,12 @@
# Scrapy documentation build configuration file, created by # Configuration file for the Sphinx documentation builder.
# sphinx-quickstart on Mon Nov 24 12:02:52 2008.
# #
# This file is execfile()d with the current directory set to its containing dir. # For the full list of built-in configuration values, see the documentation:
# # https://www.sphinx-doc.org/en/master/usage/configuration.html
# The contents of this file are pickled, so don't put values in the namespace
# that aren't pickleable (module imports are okay, they're removed automatically).
#
# All configuration values have a default; values that are commented out
# serve to show the default.
# pylint: disable=import-error # pylint: disable=import-error
import os import os
import sys import sys
from collections.abc import Sequence
from pathlib import Path from pathlib import Path
# If your extensions are in another directory, add it here. If the directory # If your extensions are in another directory, add it here. If the directory
@ -20,36 +15,30 @@ sys.path.append(str(Path(__file__).parent / "_ext"))
sys.path.insert(0, str(Path(__file__).parent.parent)) sys.path.insert(0, str(Path(__file__).parent.parent))
# General configuration # -- Project information -----------------------------------------------------
# --------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = "Scrapy"
project_copyright = "Scrapy developers"
author = "Scrapy developers"
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#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 = [ extensions = [
"hoverxref.extension", "hoverxref.extension",
"notfound.extension", "notfound.extension",
"scrapydocs", "scrapydocs",
"sphinx.ext.autodoc", "sphinx.ext.autodoc",
"scrapyfixautodoc", # Must be after "sphinx.ext.autodoc"
"sphinx.ext.coverage", "sphinx.ext.coverage",
"sphinx.ext.intersphinx", "sphinx.ext.intersphinx",
"sphinx.ext.viewcode", "sphinx.ext.viewcode",
] ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"] templates_path = ["_templates"]
exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
# The suffix of source filenames.
source_suffix = ".rst"
# The encoding of source files.
# source_encoding = 'utf-8'
# The master toctree document.
master_doc = "index"
# General information about the project.
project = "Scrapy"
copyright = "Scrapy developers"
# The version info for the project you're documenting, acts as replacement for # The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the # |version| and |release|, also used in various other places throughout the
@ -65,118 +54,17 @@ except ImportError:
version = "" version = ""
release = "" release = ""
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
language = "en"
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of documents that shouldn't be included in the build.
# unused_docs = []
exclude_patterns = ["build"]
# List of directories, relative to source directory, that shouldn't be searched
# for source files.
exclude_trees = [".build"]
# The reST default role (used for this markup: `text`) to use for all documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = "sphinx"
# List of Sphinx warnings that will not be raised
suppress_warnings = ["epub.unknown_project_files"] suppress_warnings = ["epub.unknown_project_files"]
# Options for HTML output # -- Options for HTML output -------------------------------------------------
# ----------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#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 = "sphinx_rtd_theme" html_theme = "sphinx_rtd_theme"
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# The style sheet to use for HTML and HTML Help pages. A file of that name
# must exist either in Sphinx' static/ path, or in one of the custom paths
# given in html_static_path.
# html_style = 'scrapydoc.css'
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# 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"] html_static_path = ["_static"]
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
html_last_updated_fmt = "%b %d, %Y" html_last_updated_fmt = "%b %d, %Y"
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_use_modindex = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, the reST sources are included in the HTML build as _sources/<name>.
html_copy_source = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = ''
# Output file base name for HTML help builder.
htmlhelp_basename = "Scrapydoc"
html_css_files = [ html_css_files = [
"custom.css", "custom.css",
] ]
@ -184,14 +72,8 @@ html_css_files = [
# Set canonical URL from the Read the Docs Domain # Set canonical URL from the Read the Docs Domain
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "") html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
# Options for LaTeX output # -- Options for LaTeX output ------------------------------------------------
# ------------------------ # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
# The paper size ('letter' or 'a4').
# latex_paper_size = 'letter'
# The font size ('10pt', '11pt' or '12pt').
# latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples # Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, document class [howto/manual]). # (source start file, target name, title, author, document class [howto/manual]).
@ -199,39 +81,22 @@ latex_documents = [
("index", "Scrapy.tex", "Scrapy Documentation", "Scrapy developers", "manual"), ("index", "Scrapy.tex", "Scrapy Documentation", "Scrapy developers", "manual"),
] ]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts, # -- Options for the linkcheck builder ---------------------------------------
# not chapters. # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
# latex_use_parts = False
# Additional stuff for the LaTeX preamble.
# latex_preamble = ''
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_use_modindex = True
# Options for the linkcheck builder
# ---------------------------------
# A list of regular expressions that match URIs that should not be checked when
# doing a linkcheck build.
linkcheck_ignore = [ linkcheck_ignore = [
r"http://localhost:\d+", r"http://localhost:\d+",
"http://hg.scrapy.org", "http://hg.scrapy.org",
"http://directory.google.com/", r"https://github.com/scrapy/scrapy/commit/\w+",
r"https://github.com/scrapy/scrapy/issues/\d+", r"https://github.com/scrapy/scrapy/issues/\d+",
] ]
linkcheck_anchors_ignore_for_url = ["https://github.com/pyca/cryptography/issues/2692"]
# -- Options for the Coverage extension --------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/coverage.html#configuration
# Options for the Coverage extension
# ----------------------------------
coverage_ignore_pyobjects = [ coverage_ignore_pyobjects = [
# Contract’s add_pre_hook and add_post_hook are not documented because # Contract’s add_pre_hook and add_post_hook are not documented because
# they should be transparent to contract developers, for whom pre_hook and # they should be transparent to contract developers, for whom pre_hook and
@ -272,8 +137,8 @@ coverage_ignore_pyobjects = [
] ]
# Options for the InterSphinx extension # -- Options for the InterSphinx extension -----------------------------------
# ------------------------------------- # https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#configuration
intersphinx_mapping = { intersphinx_mapping = {
"attrs": ("https://www.attrs.org/en/stable/", None), "attrs": ("https://www.attrs.org/en/stable/", None),
@ -290,11 +155,11 @@ intersphinx_mapping = {
"twistedapi": ("https://docs.twisted.org/en/stable/api/", None), "twistedapi": ("https://docs.twisted.org/en/stable/api/", None),
"w3lib": ("https://w3lib.readthedocs.io/en/latest", None), "w3lib": ("https://w3lib.readthedocs.io/en/latest", None),
} }
intersphinx_disabled_reftypes = [] intersphinx_disabled_reftypes: Sequence[str] = []
# Options for sphinx-hoverxref options # -- Options for sphinx-hoverxref extension ----------------------------------
# ------------------------------------ # https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html
hoverxref_auto_ref = True hoverxref_auto_ref = True
hoverxref_role_types = { hoverxref_role_types = {
@ -309,15 +174,3 @@ hoverxref_role_types = {
"signal": "tooltip", "signal": "tooltip",
} }
hoverxref_roles = ["command", "reqmeta", "setting", "signal"] hoverxref_roles = ["command", "reqmeta", "setting", "signal"]
def setup(app):
app.connect("autodoc-skip-member", maybe_skip_member)
def maybe_skip_member(app, what, name, obj, skip, options):
if not skip:
# autodocs was generating a text "alias of" for the following members
# https://github.com/sphinx-doc/sphinx/issues/4422
return name in {"default_item_class", "default_selector_class"}
return skip