170 lines
9.6 KiB
Plaintext
170 lines
9.6 KiB
Plaintext
---
|
|
description: This rule file provides comprehensive guidelines for writing high-quality Sphinx documentation, covering code style, structure, performance, and best practices. It aims to ensure consistency, readability, and maintainability of Sphinx-based projects.
|
|
globs: *.rst
|
|
---
|
|
- **Use reStructuredText (reST) or MyST markdown:** These are the primary markup languages for Sphinx. reST is the default and provides powerful semantic markup capabilities. MyST is a markdown flavor compatible with Sphinx. Choose one and stick to it for consistency.
|
|
|
|
- **Follow PEP 8 and PEP 257:** Adhere to PEP 8 for Python code style within your documentation, emphasizing readability and consistency (e.g., 4 spaces for indentation, line length limits). Follow PEP 257 for docstring conventions for Python code.
|
|
|
|
- **Structure Your Documentation Hierarchically:** Organize documentation into a clear, hierarchical structure with logical sections. Use proper headings (H1, H2, etc.) to delineate content.
|
|
|
|
- **Use Semantic Markup:** Leverage reST's semantic markup for functions, classes, modules, and other code elements to enable cross-referencing and automatic linking. Example: `:func:`my_function``.
|
|
|
|
- **Cross-Referencing:** Utilize Sphinx's cross-referencing capabilities extensively to link related documentation sections, functions, classes, and other elements. This improves navigation and understanding. Use `:ref:`, `:func:`, `:class:`, `:mod:` roles.
|
|
|
|
- **Document Code:** Use Sphinx's `autodoc` extension to automatically generate documentation from Python docstrings. Ensure your docstrings are comprehensive, following PEP 257 conventions. Include parameters, return types, and exceptions.
|
|
|
|
- **Use Code Blocks:** Clearly define code blocks using the `.. code-block:: language` directive to enable syntax highlighting and improve readability.
|
|
|
|
- **Whitespace and Formatting:** Maintain consistent whitespace for clarity. Use blank lines to separate sections and ensure code blocks are clearly defined.
|
|
|
|
- **Maintain Line Length:** Limit line lengths to 79 characters for code and 72 characters for docstrings/comments to improve readability and compatibility with various tools and editors.
|
|
|
|
- **Version Control:** Use version control (e.g., Git) to manage your Sphinx documentation project. This allows for tracking changes, collaboration, and easy rollback to previous versions.
|
|
|
|
- **Use a Sphinx Theme:** Choose a Sphinx theme that suits your project's style and audience. Many built-in themes (alabaster, classic, sphinxdoc) and third-party themes (sphinx_rtd_theme, pydata_sphinx_theme) are available.
|
|
|
|
- **Configure Sphinx Properly:** Carefully configure Sphinx using the `conf.py` file to customize the output format, extensions, theme, and other settings. Use meaningful project metadata (name, version, author).
|
|
|
|
- **Test Your Documentation:** Use Sphinx's `doctest` extension to automatically test code snippets within your documentation. This ensures the code examples are correct and up-to-date.
|
|
|
|
- **Use Extensions:** Explore and utilize Sphinx extensions to enhance your documentation with features like mathematical equations, diagrams, and other specialized content.
|
|
|
|
- **Internationalization:** Consider internationalizing your documentation using Sphinx's internationalization features if your project targets a global audience.
|
|
|
|
- **Linkcheck Builder:** Use the linkcheck builder to automatically check for broken links in your documentation. This ensures the documentation remains up-to-date and accurate.
|
|
|
|
- **Contribute Extensions**: Create your own sphinx extensions to manage repeated formatting or add complex rendering.
|
|
|
|
- **Naming Conventions**
|
|
- Use descriptive and consistent names for files, directories, and variables.
|
|
- Follow Python's naming conventions for modules, classes, functions, and variables.
|
|
- Use all lowercase for modules. Use underscores if it improves readability. Example: `my_module.py`
|
|
- Use CapWords for class names. Example: `MyClass`
|
|
- Use lowercase with underscores for functions and variables. Example: `my_function`, `my_variable`
|
|
- Use UPPERCASE with underscores for constants. Example: `MAX_VALUE`
|
|
|
|
- **Common Patterns and Anti-Patterns**
|
|
- **Pattern:** Use the Model-View-Controller (MVC) pattern for complex documentation structures, where the Model represents the data, the View renders the data, and the Controller handles user interactions.
|
|
- **Anti-Pattern:** Avoid deeply nested directory structures, which can make it difficult to navigate and maintain the documentation.
|
|
- **Anti-Pattern:** Avoid inconsistent formatting and style throughout the documentation, which can make it look unprofessional and difficult to read.
|
|
|
|
- **Performance Considerations**
|
|
- Optimize images by compressing them without sacrificing quality.
|
|
- Use lazy loading for large images or other resources that are not immediately visible on the page.
|
|
- Use caching to reduce the number of times that resources need to be loaded.
|
|
- Minify CSS and JavaScript files to reduce their size.
|
|
|
|
- **Security Best Practices**
|
|
- Sanitize user inputs to prevent cross-site scripting (XSS) attacks.
|
|
- Use HTTPS to encrypt communication between the user's browser and the server.
|
|
- Keep Sphinx and its extensions up-to-date to patch security vulnerabilities.
|
|
|
|
- **Testing Approaches**
|
|
- Write unit tests for custom Sphinx extensions.
|
|
- Use integration tests to verify that the different parts of the documentation work together correctly.
|
|
- Use end-to-end tests to simulate user interactions with the documentation and verify that the documentation behaves as expected.
|
|
|
|
- **Common Pitfalls and Gotchas**
|
|
- Be aware of the different versions of Sphinx and their compatibility with different Python versions and extensions.
|
|
- Use the appropriate encoding for your documentation files (UTF-8 is recommended).
|
|
- Be careful when using the `raw` directive, as it can introduce security vulnerabilities if not used properly.
|
|
|
|
- **Tooling and Environment**
|
|
- Use a code editor or IDE with syntax highlighting and linting for reStructuredText or Markdown.
|
|
- Use a build automation tool (e.g., Make, tox) to automate the documentation build process.
|
|
- Use a CI/CD system (e.g., Jenkins, Travis CI, GitHub Actions) to automatically build and deploy the documentation whenever the code changes.
|
|
|
|
- **Deployment Best Practices**
|
|
- Use a dedicated server or hosting platform for your documentation.
|
|
- Use a content delivery network (CDN) to distribute your documentation to users around the world.
|
|
- Use HTTPS to secure your documentation.
|
|
- Use a robots.txt file to prevent search engines from indexing sensitive parts of your documentation.
|
|
|
|
- **Documenting Objects**
|
|
- Use `autodoc` to automatically generate documentation for Python objects.
|
|
- Use directives like `.. automodule::`, `.. autoclass::`, and `.. autofunction::` to document modules, classes, and functions, respectively.
|
|
- Use the `:members:`, `:undoc-members:`, and `:show-inheritance:` options to control which members are documented.
|
|
- Write clear and concise docstrings for all objects, following PEP 257 conventions.
|
|
|
|
- **Intersphinx**
|
|
- Use the `intersphinx` extension to link to documentation of other Sphinx projects.
|
|
- Configure `intersphinx_mapping` in `conf.py` to specify the locations of other Sphinx documentation.
|
|
- Use the `:py:mod:`, `:py:class:`, and `:py:func:` roles to link to modules, classes, and functions in other projects.
|
|
|
|
- **reStructuredText Specific Tips**
|
|
- Use titles and sections to structure your documentation.
|
|
- Use bullet lists and numbered lists to present information in a clear and concise way.
|
|
- Use tables to organize data.
|
|
- Use images to illustrate concepts.
|
|
- Use footnotes and citations to provide additional information and give credit to sources.
|
|
|
|
- **Example `conf.py` settings:**
|
|
python
|
|
# Configuration file for the Sphinx documentation builder.
|
|
# For the full list of built-in configuration values, see the documentation:
|
|
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
|
|
|
# -- Project information -----------------------------------------------------
|
|
|
|
project = 'My Project'
|
|
copyright = '2023, My Company'
|
|
author = 'John Doe'
|
|
release = '1.0.0'
|
|
|
|
# -- General configuration ---------------------------------------------------
|
|
|
|
extensions = [
|
|
'sphinx.ext.autodoc',
|
|
'sphinx.ext.napoleon',
|
|
'sphinx.ext.intersphinx',
|
|
'sphinx.ext.todo',
|
|
'sphinx.ext.viewcode',
|
|
'sphinx.ext.mathjax',
|
|
'sphinx.ext.ifconfig',
|
|
'sphinx.ext.githubpages',
|
|
'sphinx.ext.graphviz'
|
|
]
|
|
|
|
templates_path = ['_templates']
|
|
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
|
|
|
language = 'en'
|
|
|
|
# -- Options for HTML output -------------------------------------------------
|
|
|
|
html_theme = 'sphinx_rtd_theme'
|
|
html_static_path = ['_static']
|
|
|
|
# -- Extension configuration -------------------------------------------------
|
|
|
|
# napoleon configuration (for Google-style docstrings)
|
|
napoleon_google_docstring = True
|
|
napoleon_include_init_with_doc = True
|
|
napoleon_include_private_with_doc = False
|
|
napoleon_include_special_with_doc = True
|
|
napoleon_use_rtype = True
|
|
napoleon_use_param = True
|
|
|
|
# intersphinx configuration
|
|
intersphinx_mapping = {
|
|
'python': ('https://docs.python.org/3', None),
|
|
'numpy': ('https://numpy.org/doc/stable/', None),
|
|
}
|
|
|
|
# todo configuration
|
|
todo_include_todos = True
|
|
|
|
# graphviz configuration
|
|
graphviz_output_format = 'svg'
|
|
|
|
|
|
# -- Options for Markdown files --------------------------------------------
|
|
|
|
from recommonmark.parser import CommonMarkParser
|
|
|
|
source_parsers = {
|
|
'.md': CommonMarkParser,
|
|
}
|
|
|
|
source_suffix = ['.rst', '.md'] |