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

Include C construct directives for RST checks #109

Open
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

hugovk
Copy link
Collaborator

@hugovk hugovk commented Jan 16, 2024

Fixes #108.

Add the "cross-referencing C constructs" from:

https://www.sphinx-doc.org/en/master/usage/domains/c.html#cross-referencing-c-constructs

The 3.13/Ubuntu job fails as expected, because it also checks the friend projects, and finds the two CPython examples mentioned in the issue:

sphinx-lint/tests/fixtures/friends/cpython/Doc/c-api/function.rst:171: default role used (hint: for inline literals, use double backticks) (default-role)
sphinx-lint/tests/fixtures/friends/cpython/Doc/c-api/code.rst:171: default role used (hint: for inline literals, use double backticks) (default-role)

Also Git ignore coverage data files (for example: .coverage.Hugos-MacBook-Pro.local.95733.XMjioudx).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In https://github.com/sphinx-contrib/sphinx-lint/pull/26/files#diff-91cfb2b6e0fd957947632d6fee27472ac6aaff7d825f02bdea3e54cda9005b0b, which I haven't had the time to revisit, I enumerated the list of directives more exhaustively:

DIRECTIVES_CONTAINING_RST = [
    # reStructuredText directives:
    'admonition', 'attention', 'caution', 'class', 'compound', 'container',
    'danger', 'epigraph', 'error', 'figure', 'footer', 'header', 'highlights',
    'hint', 'image', 'important', 'line-block', 'list-table', 'math', 'meta',
    'note', 'parsed-literal', 'pull-quote', 'replace', 'sidebar', 'tip',
    'topic', 'warning',
    # Added by Sphinx:
    'acks', 'centered', 'codeauthor', 'default-domain', 'deprecated(?!-removed)',
    'describe', 'highlight', 'hlist', 'index', 'literalinclude', 'moduleauthor',
    'object', 'only', 'rst-class', 'sectionauthor', 'seealso', 'tabularcolumns',
    'toctree', 'versionadded', 'versionchanged',
    # Added by Sphinx (since removed):
    'highlightlang',  # removed in Sphinx 4.0
    # Added by Sphinx (Standard domain):
    'cmdoption', 'envvar', 'glossary', 'option', 'productionlist', 'program',
    # Added by Sphinx (Python domain):
    'py:attribute', 'py:class', 'py:classmethod', 'py:currentmodule', 'py:data',
    'py:decorator', 'py:decoratormethod', 'py:exception', 'py:function',
    'py:method', 'py:module', 'py:property', 'py:staticmethod',
    'attribute', 'class', 'classmethod', 'currentmodule', 'data',
    'decorator', 'decoratormethod', 'exception', 'function',
    'method', 'module', 'property', 'staticmethod',
    # Added by Sphinx (C domain):
    'c:alias', 'c:enum', 'c:enumerator', 'c:function', 'c:macro', 'c:member',
    'c:struct', 'c:type', 'c:union', 'c:var',
    'cfunction', 'cmacro', 'cmember', 'ctype', 'cvar',
    # Added by Sphinx (sphinx.ext.todo):
    'todo', 'todolist',
    # Added in Sphinx's own documentation only:
    'confval', 'event',
    # Added in the Python documentation (directives):
    'audit-event', 'audit-event-table', 'availability',
    'deprecated-removed', 'impl-detail', 'miscnews',
    # Added in the Python documentation (objects with implicit directives):
    '2to3fixer', 'opcode', 'pdbcommand',
    # Added in the Python documentation (Python domain):
    'coroutinefunction', 'coroutinemethod', 'abstractmethod',
    'awaitablefunction', 'awaitablemethod',
    'py:coroutinefunction', 'py:coroutinemethod', 'py:abstractmethod',
    'py:awaitablefunction', 'py:awaitablemethod',
]

DIRECTIVES_CONTAINING_ARBITRARY_CONTENT = [
    # reStructuredText directives:
    'code', 'code-block', 'contents', 'csv-table', 'date', 'default-role',
    'include', 'raw', 'restructuredtext-test-directive', 'role', 'rubric',
    'section-numbering', 'sectnum', 'sourcecode', 'table', 'target-notes',
    'title', 'unicode',
    # Added by Sphinx (core):
    'cssclass',
    # Added by Sphinx (Standard domain):
    'productionlist',
    # Added by Sphinx (C domain):
    'c:namespace', 'c:namespace-pop', 'c:namespace-push',
    # Added by Sphinx (sphinx.ext.autodoc):
    'autoattribute', 'autoclass', 'autodata', 'autodecorator', 'autoexception',
    'autofunction', 'automethod', 'automodule', 'autonewtypedata',
    'autonewvarattribute', 'autoproperty',
    # Added by Sphinx (sphinx.ext.doctest):
    'doctest', 'testcleanup', 'testcode', 'testoutput', 'testsetup',
    # Added in the Python documentation:
    'limited-api-list',
]

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do you suggest? Shall we wait for #26 to be merged instead, or merge this as an incremental improvement?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Default role not found in indented block
2 participants