-
Notifications
You must be signed in to change notification settings - Fork 3.1k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation for lint rule CONTENT-VISUAL missing #11479
Comments
For reference: |
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Introduce a pattern for defining linting rules. Rely on the new structure during documentation generation to automatically create a listing of all available linting rules. The new structure centralizes information about the rules (name, description, and instructions for correcting infractions). The process honors the existing convention of Markdown within descriptions. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Introduce a pattern for defining linting rules. Rely on the new structure during documentation generation to automatically create a listing of all available linting rules. The new structure centralizes information about the rules (name, description, and instructions for correcting infractions). The process honors the existing convention of Markdown within descriptions. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] #5289 [4] https://github.com/ribozz/sphinx-argparse [5] #5299 [6] #10501 [7] #11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests#5299 [6] web-platform-tests#10501 [7] web-platform-tests#11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] #5289 [4] https://github.com/ribozz/sphinx-argparse [5] #5299 [6] #10501 [7] #11479
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests#5299 [2] web-platform-tests#10501 [3] web-platform-tests#11479 [4] web-platform-tests#16268
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests#5299 [2] web-platform-tests#10501 [3] web-platform-tests#11479 [4] web-platform-tests#16268
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wpt-commits: 825f7f95c17742cc69068abc3ccc32f373b8a67f, c06b9b330ab485fa33272bfa6585d650d14af944, 685a1275cc3ed8d5c205b1bf619ce92e776b8ca9, 560fe29f9a067470feb2a9d7a79598130d61260a, 79bf4fc70ce1e3e1c584ab89b3650e7917b56db7, fa5fa41971171e41da4db073aa09e9a95b07c3a7 wpt-pr: 16458
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wp5At-commits: 02d56b7c166590601d8168dbd4e0e92532552abf, afef08f5bf1149bdf7dc4fdb1584c754d8e230a0, 238ea486f7b9adf33044dd438eb32b1151bbde4f, 22d851e14a45e0c2d044b3b595a63ba3f153f254, 970437d5648288c44152eaa4e8a73e247d343bca, 43a1f0b83446a492626ae5bb7364d080cadb2f46 wpt-pr: 16822
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wpt-commits: 825f7f95c17742cc69068abc3ccc32f373b8a67f, c06b9b330ab485fa33272bfa6585d650d14af944, 685a1275cc3ed8d5c205b1bf619ce92e776b8ca9, 560fe29f9a067470feb2a9d7a79598130d61260a, 79bf4fc70ce1e3e1c584ab89b3650e7917b56db7, fa5fa41971171e41da4db073aa09e9a95b07c3a7 wpt-pr: 16458
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wp5At-commits: 02d56b7c166590601d8168dbd4e0e92532552abf, afef08f5bf1149bdf7dc4fdb1584c754d8e230a0, 238ea486f7b9adf33044dd438eb32b1151bbde4f, 22d851e14a45e0c2d044b3b595a63ba3f153f254, 970437d5648288c44152eaa4e8a73e247d343bca, 43a1f0b83446a492626ae5bb7364d080cadb2f46 wpt-pr: 16822
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] #5289 [4] https://github.com/ribozz/sphinx-argparse [5] #5299 [6] #10501 [7] #11479
Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] #5289 [4] https://github.com/ribozz/sphinx-argparse [5] #5299 [6] #10501 [7] #11479
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests#5299 [2] web-platform-tests#10501 [3] web-platform-tests#11479 [4] web-platform-tests#16268
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wpt-commits: 825f7f95c17742cc69068abc3ccc32f373b8a67f, c06b9b330ab485fa33272bfa6585d650d14af944, 685a1275cc3ed8d5c205b1bf619ce92e776b8ca9, 560fe29f9a067470feb2a9d7a79598130d61260a, 79bf4fc70ce1e3e1c584ab89b3650e7917b56db7, fa5fa41971171e41da4db073aa09e9a95b07c3a7 wpt-pr: 16458 UltraBlame original commit: 7ca6c39754bfda28b5fcac85bd130e2c529da05d
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wp5At-commits: 02d56b7c166590601d8168dbd4e0e92532552abf, afef08f5bf1149bdf7dc4fdb1584c754d8e230a0, 238ea486f7b9adf33044dd438eb32b1151bbde4f, 22d851e14a45e0c2d044b3b595a63ba3f153f254, 970437d5648288c44152eaa4e8a73e247d343bca, 43a1f0b83446a492626ae5bb7364d080cadb2f46 wpt-pr: 16822 UltraBlame original commit: 028d18aaf359ef81dd6bbac7674c8d6d8b3b99f8
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wpt-commits: 825f7f95c17742cc69068abc3ccc32f373b8a67f, c06b9b330ab485fa33272bfa6585d650d14af944, 685a1275cc3ed8d5c205b1bf619ce92e776b8ca9, 560fe29f9a067470feb2a9d7a79598130d61260a, 79bf4fc70ce1e3e1c584ab89b3650e7917b56db7, fa5fa41971171e41da4db073aa09e9a95b07c3a7 wpt-pr: 16458 UltraBlame original commit: 7ca6c39754bfda28b5fcac85bd130e2c529da05d
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wp5At-commits: 02d56b7c166590601d8168dbd4e0e92532552abf, afef08f5bf1149bdf7dc4fdb1584c754d8e230a0, 238ea486f7b9adf33044dd438eb32b1151bbde4f, 22d851e14a45e0c2d044b3b595a63ba3f153f254, 970437d5648288c44152eaa4e8a73e247d343bca, 43a1f0b83446a492626ae5bb7364d080cadb2f46 wpt-pr: 16822 UltraBlame original commit: 028d18aaf359ef81dd6bbac7674c8d6d8b3b99f8
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wpt-commits: 825f7f95c17742cc69068abc3ccc32f373b8a67f, c06b9b330ab485fa33272bfa6585d650d14af944, 685a1275cc3ed8d5c205b1bf619ce92e776b8ca9, 560fe29f9a067470feb2a9d7a79598130d61260a, 79bf4fc70ce1e3e1c584ab89b3650e7917b56db7, fa5fa41971171e41da4db073aa09e9a95b07c3a7 wpt-pr: 16458 UltraBlame original commit: 7ca6c39754bfda28b5fcac85bd130e2c529da05d
…s, a=testonly Automatic update from web-platform-tests [docs] Re-implement build process using Sphinx Prior to this commit, WPT used the Jekyll static site generator [1] to create a website from the project documentation. Jekyll has some restrictions which limit the utility of the generated website. Sphinx [2] has a number of features which will enable future improvements to the documentation - it can including content from files located outside of the designated "documentation" directory (some maintainers prefer to organize content elsewhere [3]) - it can generate documentation for Python CLIs like wptrunner [4] - the website it produces has a fully-featured client-side search interface - it can generating documentation for arbitrary Python files (the WPT documentation occasionally falls out of sync with the project's custom linter) - it detects and reports broken links and orphaned content (the WPT documentation has suffered from both problems in the past [5] [6] [7]) - as a Python tool, it presents less friction for local development than the Ruby-based Jekyll Although Sphinx parses content in the reStructured Text format by default, the existing content in WPT is formatted in Markdown. Markdown is generally preferable for this purpose because it is more familiar to the potential contributors to WPT and because the maintainers have no immediate plans to output to a format that is not a website. In recognition of this, enable the project's support for CommonMark. [1] https://jekyllrb.com/ [2] https://www.sphinx-doc.org [3] web-platform-tests/wpt#5289 [4] https://github.com/ribozz/sphinx-argparse [5] web-platform-tests/wpt#5299 [6] web-platform-tests/wpt#10501 [7] web-platform-tests/wpt#11479 -- Use rST syntax for tables -- [docs] Introduce tables of contents In addition to enhancing content discovery for site visitors, thoroughly applying Sphinx's "table of contents" feature allows the tool to report when content is not reachable from any page on the website. So-called "orphaned" content will be integrated in a subsequent commit. By using the `eval_rst` codeblock, this project can rely on advanced features available only to reStructured Text without sacrificing the familiarity of Markdown. -- [docs] Integrate orphaned content -- [docs] Rename files to preserve original URLs Previously, the project's documentation website was built using the Jekyll static site generator. That tool requires that site content be placed within directories whose name is prefixed with an underscore character (`_`). The leading underscore is removed from the generated content, so it is not present in the URLs of the resultant website. The Sphinx tool does not use this mechanism for content designation. Directories with a leading underscore are recreated in the generated site. Rename the directories by removing the leading underscore so that the content generated by Sphinx is available at the same URL as the content generated by Jekyll. Update internal links accordingly. This change set was created using the following commands: git mv {_,}writing-tests/ git mv {_,}running-tests/ git mv {_,}reviewing-tests/ git mv {_,}admin/ git mv {_,}appendix/ git ls-files . -z | \ xargs -0 sed -i 's/_\(writing-tests\|running-tests\|reviewing-tests\|admin\|appendix\)/\1/g' -- [docs] Build w/GH Actions and deploy w/GH Pages -- wp5At-commits: 02d56b7c166590601d8168dbd4e0e92532552abf, afef08f5bf1149bdf7dc4fdb1584c754d8e230a0, 238ea486f7b9adf33044dd438eb32b1151bbde4f, 22d851e14a45e0c2d044b3b595a63ba3f153f254, 970437d5648288c44152eaa4e8a73e247d343bca, 43a1f0b83446a492626ae5bb7364d080cadb2f46 wpt-pr: 16822 UltraBlame original commit: 028d18aaf359ef81dd6bbac7674c8d6d8b3b99f8
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests#5299 [2] web-platform-tests#10501 [3] web-platform-tests#11479 [4] web-platform-tests#16268
When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] #5299 [2] #10501 [3] #11479 [4] #16268
We just merged gh-17189, so the online documentation of the lint tool now describes every available rule (including CONTENT-VISUAL): https://web-platform-tests.org/writing-tests/lint-tool.html And because that list is programmatically generated, we can have more confidence that the documentation will remain up-to-date as the rule set changes. |
…, a=testonly Automatic update from web-platform-tests [docs] Generate linting docs from source (#17189) When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479 [4] web-platform-tests/wpt#16268 -- wpt-commits: 204072e843f69e3a13628c01a928ea99aebed978 wpt-pr: 17189
…, a=testonly Automatic update from web-platform-tests [docs] Generate linting docs from source (#17189) When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479 [4] web-platform-tests/wpt#16268 -- wpt-commits: 204072e843f69e3a13628c01a928ea99aebed978 wpt-pr: 17189
…, a=testonly Automatic update from web-platform-tests [docs] Generate linting docs from source (#17189) When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479 [4] web-platform-tests/wpt#16268 -- wpt-commits: 204072e843f69e3a13628c01a928ea99aebed978 wpt-pr: 17189 UltraBlame original commit: 56fc8b1c2e129a595c1bee4822ea5c07ee630404
…, a=testonly Automatic update from web-platform-tests [docs] Generate linting docs from source (#17189) When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479 [4] web-platform-tests/wpt#16268 -- wpt-commits: 204072e843f69e3a13628c01a928ea99aebed978 wpt-pr: 17189 UltraBlame original commit: 56fc8b1c2e129a595c1bee4822ea5c07ee630404
…, a=testonly Automatic update from web-platform-tests [docs] Generate linting docs from source (#17189) When new rules have been added to WPT's "lint" tool, the corresponding documentation has not always been updated [1] [2] [3]. The static list of rules currently describes only 22 of the 53 available rules. Automatically generating documentation from source code helps avoid this state and the confusion it can cause contributors. Rely on the previously-implemented source code structure [4] during documentation generation to automatically create a listing of all available linting rules. Although the Sphinx documentation generator includes a built-in extension for generating documentation from Python source code, the output of that extension is designed to document Python primitives such as functions and classes. Such a format is inappropriate for this case because the users of the linting tool do not interact with the internals in this way. Define a custom docutils directive to tailor the documentation to the needs of its audience. [1] web-platform-tests/wpt#5299 [2] web-platform-tests/wpt#10501 [3] web-platform-tests/wpt#11479 [4] web-platform-tests/wpt#16268 -- wpt-commits: 204072e843f69e3a13628c01a928ea99aebed978 wpt-pr: 17189 UltraBlame original commit: 56fc8b1c2e129a595c1bee4822ea5c07ee630404
The docs are missing "CONTENT-VISUAL":
https://web-platform-tests.org/writing-tests/lint-tool.html
The linting message is not very helpful - it doesn't really say why a particular file was flagged as "CONTENT-VISUAL". The linting message just says to get around the problem by adding it to
lint.whitelist
, but that feels kinda wrong and getting around the problem.The text was updated successfully, but these errors were encountered: