Automated documentation checks

The command line tool doc-checker performs several checks on the documentation source. Checks that do not need to access external links are performed as presubmit checks when submitting changes to the //docs directory.

The primary goal of doc-checker is to make sure all the documents in the //docs directory are part of the interconnected graph made up of _toc.yaml files and in-page links are reachable when the documentation is published on fuchsia.dev. Other checks inspect the links themselves to enforce documentation standards and consistency.

Running doc-checker

fx doc-checker

The external link check can be skipped by adding --local-links-only.

For more options, see the full command line reference.

If it is not part of the current build configuration for some reason, re-run fx set including the option to build doc_checker: --with //tools/doc_checker:doc_checker.

These are the situations that are reported by doc-checker:

[missing doc](/docs/does_not_exist.md)

These are links that reference fuchsia.googlesource.com or fuchsia.dev and access a file in //docs. These links should be converted to file paths.

Incorrect

[unnessary link](https://fuchsia.dev/fuchsia-src/get-started/learn-fuchsia.md)

Correct

[correct link](/docs/get-started/learn-fuchsia.md)

These are projects that are included in the Fuchsia source tree which have been merged into Fuchsia or completed deprecated. The list of valid projects is part of the source code.


     [invalid old project](https://fuchsia.googlesource.com/garnet/+/refs/heads/main)

These are links that point to paths beyond the //docs directory. These should be converted to fuchsia relative paths.

Incorrect

  [source file](/docs/../src/BUILD.gn)

Correct

   [source file](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/BUILD.gn)

Missing alt text for images

Images must have meaningful alt text.

![Diagram of the state transitions](/docs/state-machine.png "State machine")

Including markdown fragment files

Markdown file fragments are included in another markdown file by using

<<relative-path-to/_file.md>>

The path must be relative to the current .md source file—absolute paths cannot be used. The << >> directive is a block directive and so must appear on a line by itself.

YAML data file checks

YAML files in fuchsia.dev are used to store documentation content in a structured format which is then rendered through the use of Jinja templates. Any YAML file that is prefixed with a _ indicates that the YAML is not published as a standalone file, but only rendered through the use of a template. If a YAML file is not prefixed with _, the YAML file is published on fuchsia.dev and can be viewed as a plain YAML file.

_toc.yaml checks

_toc.yaml files are mainly used to create the information architecture for fuchsia.dev.

These checks enforce the table of contents structure described in _toc.yaml reference.

  • top level key toc

  • entries are one of:

    • break: true - (optional) Adds a vertical break
    • contents: <list of toc entries> - (optional) The contents of a custom tab.
    • heading: <string> - (optional) The heading for a group of links.
    • include: <path to _toc.yaml> - (optional) Includes another _toc.yaml.
    • name: <string> - (optional) Name of this tab.
    • path: <string> - (optional) Path or URL to a page.
    • path_attributes: <mapping> - (optional) Name-value pairs of attributes for the link created based on the path property.
    • section: <toc entry> - (optional) Indented toc entry defining a collapsible section, usually defined via include another _toc.yaml file.
    • skip_translation: true - (optional) Prevents human and machine translation of all link titles in this entry and any descendants.
    • status: <string> - (optional) Used with heading or title and cannot be used with break or include. Applies a predefined status. The status must be one of:
    • alpha
    • beta
    • deprecated
    • experimental
    • external
    • limited
    • new
    • step_group: <string> - (optional) Used to create groups of content that have prev and next navigation links to the bottom of the pages.
    • style: <string> - (optional) Cannot be used with break or include. This style is applied to the heading or section element. This value must be accordion.
    • title: string - (optional) The link title.

  • path properties are valid paths:

    • File paths such as /docs/somewhere/file.md
    • http:// or https:// URLs.
    • /reference to generated reference documentation. These links are validated using external links to fuchsia.dev/reference.
    • Special files: /CONTRIBUTING.md and /CODE_OF_CONDUCT.md.

Pages not referenced in _toc.yaml graph

Markdown pages in //docs must appear in a _toc.yaml that is included in the graph of table of contents created from the root _toc.yaml in //docs/_toc.yaml.

Structure of _areas.yaml

TBD: _What is the structure of _areas.yaml__

Structure of _eng_council.yaml

TBD: _What is the use of _eng_council.yaml?

Structure of _metadata.yaml

TBD: _What is the use of metadata.yaml?_

Structure of _rfcs.yaml

This file defines the metadata for RFC documents.

See RFC metadata.

Structure of_roadmap.yaml

TBD: _What is the use of roadmap.yaml?_

Structure of_drivers_areas.yaml

TBD: _What is the use of _drivers_areas.yaml?

Structure of _drivers_epitaphs.yaml

TBD: _What is the use of __driversepitaphs.yaml?

Structure of_problems.yaml

TBD: _What is the use of problems.yaml?_

Structure of_redirects.yaml

This file defines redirections to another page for a given URL.

Structure of _supported_cpu_architecture.yaml

TBD: _What is the use of _supported_cpu_architecture.yaml?

Structure of_supported_sys_config.yaml

List of supported systems configurations.

See Supported system config list

Structure of_tools.yaml

TBD: _What is the use of tools.yaml?_

See: source code

Structure of_deprecated-docs.yaml

This file defines the redirection rules for deprecated documents.

See: Redirect the pages to the deprecation notice.

Structure of _glossary.yaml

This file defines the glossary of Fuchsia terminology.

See: Adding a glossary term

    [broken link](https://mispeeled.com)

Including the hl parameter for Google hosted sites

The hl parameter indicates the user's host language. This parameter should not be included in the URL since it disables the automatic redirection to translated pages if they exist.