search

jeremiah-c-leary / vhdl-style-guide

Style guide enforcement for VHDL
GNU General Public License v3.0
182 stars 38 forks source link

Various minor documentation fixes #1006

Closed JHertz5 closed 10 months ago

JHertz5 commented 12 months ago

Environment 3.17.0

Describe the bug I've noticed a few warnings popping up from Sphinx when generating the docs. Rather than creating dozens of individual issues, I thought I would collate them into one and fix them as many as I can at once (I hope that's alright).

To Reproduce Steps to reproduce the behavior:

  1. Go to the docs directory
  2. Run make html
  3. Observe the warnings produced by Sphinx: 
    
$ make html
Running Sphinx v4.3.2
making output directory... done
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 144 source files that are out of date
updating environment: [new config] 144 added, 0 changed, 0 removed
reading sources... [100%] with_rules                                                             
/home/jhertzog/code/vhdl-style-guide/docs/configuring_previous_line_rules.rst:65: WARNING: duplicate label example: require_blank_line, other instance in /home/jhertzog/code/vhdl-style-guide/docs/configuring_blank_lines.rst
/home/jhertzog/code/vhdl-style-guide/docs/configuring_selected_assignment_structure_rules.rst:561: WARNING: duplicate label example: |new_line_before_semicolon| set to |default_yes|, other instance in /home/jhertzog/code/vhdl-style-guide/docs/configuring_selected_assignment_structure_rules.rst
/home/jhertzog/code/vhdl-style-guide/docs/editor_integration/vim.rst:26: WARNING: Unknown directive type "code_block".

.. code_block:: viml function! ale_linters#vhdl#vsg_ale#GetCommand(buffer) return "vsg --config ./vsg_config.yaml -of syntastic -f " . expand('%p') endfunction

function! ale_linters#vhdl#vsg_ale#Handle(buffer, lines)
    let l:pattern = '^\(\w\{-}\):\s\+\(.*\)(\(\d\+\))\(\w\+\)\s\+--\s\+\(.*\)$'
    let l:output = []

    for l:match in ale#util#GetMatches(a:lines, l:pattern)
        call add(l:output, {
        \   'lnum': l:match[3],
        \   'col': 0,
        \   'text': l:match[2] . ": " . l:match[4] . " - Solution: " . l:match[5],
        \})
    endfor
    return l:output
endfunction

call ale#linter#Define('vhdl', {
\   'name': 'vsg_ale',
\   'executable': 'vsg',
\   'output_stream': 'stdout',
\   'lint_file': 0,
\   'command': function('ale_linters#vhdl#vsg_ale#GetCommand'),
\   'callback': 'ale_linters#vhdl#vsg_ale#Handle',
\})

/home/jhertzog/code/vhdl-style-guide/docs/editor_integration/vim.rst:72: WARNING: Unknown directive type "code_block".

.. code_block:: lua local null_ls = require('null-ls') local helpers = require('null-ls.helpers') local vsg_lint = { name = "VSG", method = null_ls.methods.DIAGNOSTICS, filetypes = { "vhdl" }, generator = helpers.generator_factory({ command = "vsg", args = function(params) local rv = {} -- check if there is a config file in the root directory, if so -- insert the -c argument with it if vim.fn.filereadable(params.root .. '/vsg_config.yaml') == 1 then table.insert(rv, '-c=' .. params.root .. '/vsg_config.yaml') end table.insert(rv, '--stdin') table.insert(rv, '-of=syntastic') return rv end, cwd = nil, check_exit_code = { 0, 1 }, from_stderr = false, ignore_stderr = true, to_stdin = true, format = "line", multiple_files = false, on_output = helpers.diagnostics.from_patterns({ { pattern = [[(%w+).%((%d+)%)(.)%s+%-%-%s+(.*)]], groups = { 'severity', 'row', 'code', 'message' }, overrides = { severities = { -- 2 is for warnings, nvim showing as an erorr can be obnoxious. Change if desired ["ERROR"] = 2, ["WARNING"] = 3, ["INFORMATION"] = 3, ["HINT"] = 4, } } } }), }) }

local vsg_format = {
    name = "VSG Formatting",
    method = null_ls.methods.FORMATTING,
    filetypes = { "vhdl" },
    generator = helpers.formatter_factory({
        command = "vsg",
        args = { "-c$ROOT/vsg_config.yaml", "-f=$FILENAME", "-of=syntastic", "--fix" },
        cwd = nil,
        check_exit_code = { 0, 1 },
        ignore_stderr = true,
        to_temp_file = true,
        from_temp_file = true,
        to_stdin = false,
        multiple_files = false,
    })
}

null_ls.setup({
    diagnostics_format = "[#{c}] #{m} (#{s})",
    sources = { vsg_lint, vsg_format }
})

/home/jhertzog/code/vhdl-style-guide/docs/editor_integration/vscode.rst:8: WARNING: duplicate label configuring, other instance in /home/jhertzog/code/vhdl-style-guide/docs/configuring.rst /home/jhertzog/code/vhdl-style-guide/docs/overview.rst:2: WARNING: duplicate label overview, other instance in /home/jhertzog/code/vhdl-style-guide/docs/configuring_overview.rst /home/jhertzog/code/vhdl-style-guide/docs/rule_groups/overview.rst:2: WARNING: duplicate label overview, other instance in /home/jhertzog/code/vhdl-style-guide/docs/overview.rst /home/jhertzog/code/vhdl-style-guide/docs/rule_groups/whitespace_rule_group.rst:3: WARNING: Title underline too short.

Whitespace Rule Group

/home/jhertzog/code/vhdl-style-guide/docs/rule_groups/whitespace_rule_group.rst:6: WARNING: Title underline too short.

Rules Enforcing Whitespace Rule Group #################################### /home/jhertzog/code/vhdl-style-guide/docs/styles.rst:85: WARNING: duplicate label example, other instance in /home/jhertzog/code/vhdl-style-guide/docs/configuring_whitespace_after_comment_rules.rst /home/jhertzog/code/vhdl-style-guide/docs/theory_of_operation/rule_selection.rst:27: WARNING: duplicate label example, other instance in /home/jhertzog/code/vhdl-style-guide/docs/styles.rst looking for now-outdated files... none found pickling environment... done checking consistency... /home/jhertzog/code/vhdl-style-guide/docs/api.rst: WARNING: document isn't included in any toctree /home/jhertzog/code/vhdl-style-guide/docs/configuring_selected_assignment_structure_rules.rst: WARNING: document isn't included in any toctree /home/jhertzog/code/vhdl-style-guide/docs/notepad_pp.rst: WARNING: document isn't included in any toctree /home/jhertzog/code/vhdl-style-guide/docs/release_process.rst: WARNING: document isn't included in any toctree /home/jhertzog/code/vhdl-style-guide/docs/theory_of_operation/rule_selection.rst: WARNING: document isn't included in any toctree done preparing documents... done writing output... [100%] with_rules
links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules /home/jhertzog/code/vhdl-style-guide/docs/links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules /home/jhertzog/code/vhdl-style-guide/docs/links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules links.rst:12: WARNING: undefined label: configuring-conditional-expressions-structure-rules links.rst:42: WARNING: Failed to create a cross reference. A title or caption not found: configuring-simple-multiline-structure-rules generating indices... genindex done writing additional pages... search done copying images... [100%] editor_integration/vscode_file_fixed.png
copying static files... done copying extra files... done dumping search index in English (code: en)... done dumping object inventory... done build succeeded, 160 warnings.

The HTML pages are in _build/html.



**Expected behavior**
Most, if not all, of these warnings should be corrected.

**Screenshots**
None

**Additional context**
None