Uploaded image for project: 'Documentation'
  1. Documentation
  2. DOC-268

Eliminate RST Errors/Warnings and Linkcheck Errors

XMLWordPrintable

    • Icon: Story Story
    • Resolution: Done
    • Icon: Medium Medium
    • Casablanca Release
    • None
    • None
    • None

      In the doc project and related project repositories that provide documentation RST source, there will be no Sphinx html builder or  link check builder errors/warnings in the Beijing branch.

      Most existing errors / warnings will be eliminated by:

      1. Consistent use of a blank line to separate a current block from other markup or directives that imply start of a new block..
      2. Using balanced RST inline markup start/stop delimiters
      3. Referencing URLs that are valid or use a pattern that link check ignores (see line 380 linkcheck_ignore in sphinx configuration for the current list).
      4. Use of the sphinx code-block directives with "source code" that complies with the syntax of the language specified for the code-block.   Source code in an rst file, outside of code-block directive and/or mixed languages within a code-block should be avoided. For example specifying a code-block of type http for a URL that contains some form of macro or variable substitution convention.    If a code-block must contain content that is inconsistent with all code-block supported  language types, specify  "none" as the code-block language.   A before/after example of  code blocks to improve readability and eliminate errors/warnings in html and rst is attached.

            rb2745 rb2745
            rb2745 rb2745
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: