Skip to content
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

Closed
marcoscaceres opened this issue Jun 12, 2018 · 2 comments
Closed

Documentation for lint rule CONTENT-VISUAL missing #11479

marcoscaceres opened this issue Jun 12, 2018 · 2 comments

Comments

@marcoscaceres
Copy link
Contributor

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.

@marcoscaceres
Copy link
Contributor Author

@marcoscaceres marcoscaceres changed the title Documentation for CONTENT-VISUAL missing Documentation for lint rule CONTENT-VISUAL missing Jun 12, 2018
jugglinmike added a commit to bocoup/wpt-docs that referenced this issue Mar 22, 2019
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
jugglinmike added a commit to bocoup/wpt-docs that referenced this issue Mar 29, 2019
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
jugglinmike added a commit to bocoup/wpt-docs that referenced this issue Mar 29, 2019
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
jugglinmike added a commit to bocoup/wpt-docs that referenced this issue Mar 29, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue Apr 23, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue Apr 23, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue May 2, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue May 2, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue May 2, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue May 8, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue May 13, 2019
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
jgraham pushed a commit that referenced this issue May 13, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue May 14, 2019
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
gsnedders pushed a commit that referenced this issue May 14, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue Jun 5, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue Jun 5, 2019
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
moz-v2v-gh pushed a commit to mozilla/gecko-dev that referenced this issue Jun 19, 2019
…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
moz-v2v-gh pushed a commit to mozilla/gecko-dev that referenced this issue Jun 19, 2019
…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
xeonchen pushed a commit to xeonchen/gecko that referenced this issue Jun 19, 2019
…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
xeonchen pushed a commit to xeonchen/gecko that referenced this issue Jun 19, 2019
…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
marcoscaceres pushed a commit that referenced this issue Jul 23, 2019
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
marcoscaceres pushed a commit that referenced this issue Jul 23, 2019
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
jugglinmike added a commit to bocoup/wpt that referenced this issue Sep 5, 2019
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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-comments-removed that referenced this issue Oct 4, 2019
…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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-comments-removed that referenced this issue Oct 4, 2019
…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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified that referenced this issue Oct 4, 2019
…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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified that referenced this issue Oct 4, 2019
…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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified-and-comments-removed that referenced this issue Oct 4, 2019
…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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified-and-comments-removed that referenced this issue Oct 4, 2019
…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
jugglinmike added a commit to bocoup/wpt that referenced this issue Nov 11, 2019
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
jugglinmike added a commit that referenced this issue Nov 14, 2019
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
@jugglinmike
Copy link
Contributor

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.

moz-v2v-gh pushed a commit to mozilla/gecko-dev that referenced this issue Nov 29, 2019
…, 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
xeonchen pushed a commit to xeonchen/gecko that referenced this issue Nov 29, 2019
…, 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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-comments-removed that referenced this issue Nov 30, 2019
…, 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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified-and-comments-removed that referenced this issue Nov 30, 2019
…, 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
gecko-dev-updater pushed a commit to marco-c/gecko-dev-wordified that referenced this issue Nov 30, 2019
…, 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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants