Sylvestre Ledru
21ec718ad5
Caused by the Sphinx 7.4.7 -> 9.0.4 upgrade earlier in this stack: BuildEnvironment.relfn2path used to normalise with path.normpath(), and now uses Path.resolve(). Since the docs are built from a staging tree of symlinks into the source tree, resolve() follows the symlink of the document being linked to and lands outside the Sphinx source directory, so myst-parser reports "Unknown source document" - 1339 warnings on a clean build. Override relfn2path to normalise textually again, so ".." still collapses but the path stays in the staging tree. Known failures drop from 1624 to 298. The 13 newly reported ones are the already-allowlisted "local id not found in doc": links reaching the right document but a stale anchor, previously masked by the link failing outright. Differential Revision: https://phabricator.services.mozilla.com/D324436
268 lines
12 KiB
YAML
268 lines
12 KiB
YAML
---
|
|
|
|
# The order of the main categories are defined in index.md
|
|
# Sub categories orders are preserved
|
|
categories:
|
|
overview_doc:
|
|
- glossary
|
|
- overview
|
|
setup_doc:
|
|
- setup
|
|
contributing_doc:
|
|
- contributing
|
|
- bug-mgmt
|
|
- crash-reporting
|
|
user_guide:
|
|
- devtools-user
|
|
source_doc:
|
|
- mots
|
|
- browser
|
|
- dom
|
|
- editor
|
|
- layout
|
|
- gfx
|
|
- ipc
|
|
- devtools
|
|
- toolkit
|
|
- js
|
|
- jsloader
|
|
- mobile/android/geckoview
|
|
- mobile/android/fenix
|
|
- mobile/android/focus-android
|
|
- dom/bindings/webidl
|
|
- modules/libpref
|
|
- networking
|
|
- remote
|
|
- services
|
|
- permissions
|
|
- uriloader
|
|
- widget/cocoa
|
|
- widget/windows
|
|
- toolkit/components/ml
|
|
- accessible
|
|
- media
|
|
- code-quality
|
|
- writing-rust-code
|
|
- rust-components
|
|
- tools/profiler
|
|
- performance
|
|
- storage
|
|
- xpcom
|
|
- nspr
|
|
- security/nss
|
|
- content-security
|
|
- rlbox
|
|
build_doc:
|
|
- mach
|
|
- tools/try
|
|
- build/buildsystem
|
|
- taskcluster
|
|
- tools/moztreedocs
|
|
- mozbuild/vendor
|
|
testing_doc:
|
|
- testing/automated-testing
|
|
- testing/treeherder-try
|
|
- testing/sheriffed-intermittents
|
|
- testing/tests-for-new-config
|
|
- testing/intermittent
|
|
- testing/debugging-intermittents
|
|
- testing/testing-policy
|
|
- testing/ci-configs
|
|
- testing/browser-chrome
|
|
- testing/chrome-tests
|
|
- testing/geckodriver
|
|
- testing/test-verification
|
|
- testing/webrender
|
|
- testing/mochitest-plain
|
|
- testing/xpcshell
|
|
- testing/tps
|
|
- web-platform
|
|
- gtest
|
|
- tools/fuzzing
|
|
- tools/sanitizer
|
|
- testing/perfdocs
|
|
- tools/code-coverage
|
|
- testing-rust-code
|
|
ai_agent_tools_doc:
|
|
- ai-agent-tools
|
|
release_doc:
|
|
- update-infrastructure
|
|
- tools/update-verify
|
|
l10n_doc:
|
|
- intl
|
|
- l10n
|
|
python_doc:
|
|
- mozbase
|
|
- python
|
|
fennec_doc:
|
|
- mobile/android
|
|
metrics_doc:
|
|
- metrics
|
|
|
|
redirects:
|
|
performance/memory/memory.html: devtools-user/memory/index.html
|
|
performance/memory/basic_operations.html: devtools-user/memory/basic_operations/index.html
|
|
performance/memory/aggregate_view.html: devtools-user/memory/aggregate_view/index.html
|
|
performance/memory/tree_map_view.html: devtools-user/memory/tree_map_view/index.html
|
|
performance/memory/dominators.html: devtools-user/memory/dominators/index.html
|
|
performance/memory/dominators_view.html: devtools-user/memory/dominators_view/index.html
|
|
performance/memory/DOM_allocation_example.html: devtools-user/memory/dom_allocation_example/index.html
|
|
performance/memory/monster_example.html: devtools-user/memory/monster_example/index.html
|
|
browser/browser: browser
|
|
browser/components/newtab/docs/index.html: browser/extensions/newtab/docs/index.html
|
|
browser/tabunloader/index.html: browser/components/tabbrowser/docs/tab-unloading.html
|
|
contributing/how_to_contribute_firefox.html: contributing/contribution_quickref.html
|
|
mobile/android/geckoview/contributor/contributing-to-firefox.html: contributing/contribution_quickref.html
|
|
contributing/artifact_builds.html: contributing/build/artifact_builds.html
|
|
contributing/linux_build.html: setup/linux_build.html
|
|
contributing/build/linux_build.html: setup/linux_build.html
|
|
contributing/vscode.html: contributing/editors/vscode.html
|
|
contributing/build/supported.html: build/buildsystem/supported-configurations.html
|
|
dom/dom: dom
|
|
layout/layout: layout
|
|
gfx/gfx: gfx
|
|
intl/l10n/l10n: l10n
|
|
ipc/ipc: ipc
|
|
modules/libpref/libpref: modules/libpref
|
|
python/mach: mach
|
|
python/python: python
|
|
setup/getting_set_up.html: contributing/contributing_to_mozilla.html
|
|
taskcluster/taskcluster: taskcluster
|
|
testing/geckodriver/geckodriver: testing/geckodriver
|
|
testing/marionette/marionette: remote/marionette
|
|
testing/marionette: remote/marionette
|
|
toolkit/components/telemetry/telemetry: toolkit/components/telemetry
|
|
tools/compare-locales/index.html: build/buildsystem/locales.html
|
|
tools/docs/index.html: tools/moztreedocs/index.html
|
|
tools/docs/contribute/how_to_contribute_firefox.html: contributing/how_to_contribute_firefox.html
|
|
tools/docs/contribute/directory_structure.html: contributing/directory_structure.html
|
|
tools/lint: code-quality/lint
|
|
tools/lint/coding-style: code-quality/coding-style
|
|
tools/static-analysis/index.html: code-quality/static-analysis.html
|
|
|
|
# Please do not add more exceptions to these warnings. Generally they should be
|
|
# fixable. If you need help please ask in the firefox-source-docs channel on Matrix.
|
|
allowed_warnings:
|
|
# General warnings that need consideration/fixing.
|
|
- "WARNING: document isn't included in any toctree"
|
|
- "WARNING: local id not found in doc"
|
|
- "WARNING: 'myst' cross-reference target not found"
|
|
- "WARNING: Lexing literal_block"
|
|
- "WARNING: dot command 'dot' cannot be run \\(needed for graphviz output\\)"
|
|
# Specific warnings allowed when the allow list was created.
|
|
- "testing/automated-testing/manifest-sandbox\\.md:.*: WARNING: download file not readable"
|
|
- "UITour-lib.Mozilla.UITour.* WARNING: duplicate class description of Mozilla.UITour"
|
|
- "uitour/docs/index\\.md:.*: WARNING: duplicate class description of Mozilla\\.UITour"
|
|
# Undefined label warnings.
|
|
- "dom/navigation/nav_replace\\.md:.*: WARNING: undefined label"
|
|
- "devtools-user/page_inspector/how_to/work_with_animations/index\\.md:.*: WARNING: undefined label"
|
|
# Bug 1915274 - Clean up documentation warnings in NSS
|
|
- "security/nss/.* WARNING: undefined label"
|
|
- "WARNING: duplicate label header-files, other instance in"
|
|
- "security/nss/.* WARNING: duplicate label"
|
|
- "security/nss/.* WARNING: more than one target found for 'myst' cross-reference"
|
|
# Various python issues
|
|
- "\\.py:.* WARNING: duplicate object description"
|
|
# Sphinx >= 8 reports these against <unknown> rather than the .py file.
|
|
- "<unknown>:.*: WARNING: duplicate object description"
|
|
- "missing attribute .* in object mozprocess.ProcessHandlerMixin"
|
|
# Sphinx >= 8 wording for the same missing mozprocess attributes.
|
|
- "attribute .* is listed in :members: but is missing .*mozprocess\\.processhandler\\.ProcessHandlerMixin"
|
|
# Sphinx >= 8 reworded this from "failed to import module 'X'" to
|
|
# "failed to import 'X' from module 'Y'", and autosummary grew its own
|
|
# "Failed to import" variant for the same underlying failures.
|
|
- "WARNING: autodoc: failed to import"
|
|
- "WARNING: Failed to import "
|
|
# Sphinx >= 8 autosummary checks source_suffix for .rst, which the tree
|
|
# no longer registers now that the docs are markdown.
|
|
- "WARNING: autosummary generates \\.rst files internally"
|
|
- "WARNING: invalid signature for automodule \\('mozbuild.action.xpidl-process'\\)"
|
|
- "WARNING: don't know which module to import for autodocumenting"
|
|
# Sphinx >= 8 reports ambiguous python cross-references that older versions
|
|
# resolved silently.
|
|
- "gecko_taskgraph\\.util\\.md.*WARNING: more than one target found for cross-reference"
|
|
# This file has various warnings that need investigation.
|
|
- "python/mozbuild/mozbuild/frontend/context\\.py"
|
|
# mozbuild.sphinx extension warnings.
|
|
- "WARNING: the mozbuild.sphinx extension does not declare"
|
|
- "WARNING: doing serial read"
|
|
# Bug 2008577 - docutils rejects some JSDoc prose in these modules under
|
|
# myst-parser 5. The markup lives in the JS sources, not these documents.
|
|
- "webextensions/reference\\.md:.*: ERROR: Unexpected indentation"
|
|
- "webextensions/reference\\.md:.*: WARNING: Block quote ends without a blank line"
|
|
- "addon-manager/AddonManager\\.md:.*: ERROR: Unexpected indentation"
|
|
- "addon-manager/AddonManager\\.md:.*: WARNING: Block quote ends without a blank line"
|
|
- "xpcom/xpcomutils\\.md:.*: WARNING: Inline interpreted text or phrase reference start-string without end-string"
|
|
- "xpcom/xpcomutils\\.md:.*: WARNING: Explicit markup ends without a blank line"
|
|
# Bug 2008577 - The Rust component API docs are generated by uniffi outside
|
|
# this tree, so their markup cannot be fixed here.
|
|
- "rust-components/api/js/.*: WARNING: Inline literal start-string without end-string"
|
|
- "rust-components/api/js/.*: WARNING: Inline interpreted text or phrase reference start-string without end-string"
|
|
- "rust-components/api/js/.*: WARNING: Bullet list ends without a blank line"
|
|
|
|
# Paths to exclude from documentation staging to avoid duplicate builds
|
|
- "devtools-user/debugger-api/index\\.md:.*: WARNING: unknown document"
|
|
- "devtools-user/memory/aggregate_view/index\\.md:.*: WARNING: unknown document"
|
|
- "devtools-user/migrating_from_firebug/index\\.md:.*: WARNING: unknown document"
|
|
- "devtools-user/tips/index\\.md:.*: WARNING: unknown document"
|
|
- "devtools-user/tools_toolbox/index\\.md:.*: WARNING: unknown document"
|
|
- "devtools-user/web_console/console_messages/index\\.md:.*: ERROR: Undefined substitution referenced"
|
|
# mdn-imported content with image width values that confuse the parser.
|
|
- "ipc/ipdl\\.md:.*: WARNING: Duplicate explicit target name"
|
|
- "contributing/.*\\.md:.*: WARNING: undefined label"
|
|
- "permissions\\.py:.*: ERROR: Unknown target name: \"server-locations\\.txt\""
|
|
- "toolkit/components/telemetry/data/install-ping\\.md:.*: ERROR: Document or section may not begin with a transition"
|
|
exclude_patterns:
|
|
- js/src/doc/Debugger
|
|
|
|
# JSDoc must run successfully for dirs specified, so running
|
|
# tree-wide (the default) will not work currently.
|
|
# When adding more paths to this list, please ensure that they are not
|
|
# excluded from the valid-jsdoc and require-jsdoc sections in the top-level
|
|
# eslint-rollouts.config.mjs.
|
|
js_source_paths:
|
|
- browser/components/backup
|
|
- browser/components/backup/actors
|
|
- browser/components/backup/resources
|
|
- browser/components/customizableui
|
|
- browser/components/extensions
|
|
- browser/components/migration
|
|
- browser/components/migration/content
|
|
- browser/components/mozcachedohttp
|
|
- browser/components/mozcachedohttp/actors
|
|
# Limited to SessionStore.sys.mjs, the only file in the directory that has
|
|
# a documentation page.
|
|
- browser/components/sessionstore/SessionStore.sys.mjs
|
|
# Limited to Tabbrowser.sys.mjs: the rest of the directory holds window
|
|
# scripts and tests whose bare globals and duplicate local names trip
|
|
# https://github.com/pyodide/sphinx-js/issues/242 or a variant of it.
|
|
- browser/components/tabbrowser/Tabbrowser.sys.mjs
|
|
- browser/components/uitour
|
|
- browser/components/urlbar
|
|
- browser/components/urlbar/content
|
|
# Limited to URILoadingHelper.sys.mjs: the rest of the directory holds
|
|
# modules which do not currently run cleanly for jsdoc.
|
|
- browser/modules/URILoadingHelper.sys.mjs
|
|
- js/xpconnect/loader
|
|
- remote/marionette
|
|
- testing/mochitest/BrowserTestUtils
|
|
- testing/mochitest/tests/SimpleTest/SimpleTest.js
|
|
- testing/mochitest/tests/SimpleTest/EventUtils.js
|
|
- testing/modules/Assert.sys.mjs
|
|
- testing/modules/TestUtils.sys.mjs
|
|
- toolkit/actors
|
|
- toolkit/components/extensions
|
|
- toolkit/components/extensions/parent
|
|
- toolkit/components/ml/content/backends/ONNXPipeline.mjs
|
|
- toolkit/modules/BrowserUtils.sys.mjs
|
|
- toolkit/mozapps/extensions
|
|
- toolkit/components/prompts/src
|
|
- toolkit/components/pictureinpicture
|
|
- toolkit/components/pictureinpicture/content
|
|
# This is limited to SearchService.sys.mjs for now, as we only need to
|
|
# generate docs for that file currently. Other search files
|
|
# (e.g. SearchEngineSelector) are failing due to
|
|
# https://github.com/pyodide/sphinx-js/issues/242 or a variant of it.
|
|
- toolkit/components/search/SearchService.sys.mjs
|
|
- toolkit/components/uniffi-bindgen-gecko-js/components/generated
|