PyAnsys documentation resources#

This page lists resources relevant to contributing to PyAnsys documentation. While other pages reference resources as needed, this page provides a central location from which you can easily view all referenced resources.

Style and formatting resources#

The following alphabetized list of resources provide guidelines for writing PyAnsys documentation. These resources provide you with an understanding of how to write and format PyAnsys documentation content correctly in various types of source files.

  • GitHub Flavored Markdown Spec: Describes how GitHub Flavored Markdown is a dialect of Markdown supported for user content on GitHub.com and GitHub Enterprise. Generally, all manually written source files for PyAnsys documentation are RST files. However, some projects use a GitHub Flavored Markdown (MD) file for the project’s README file. For more information, see README.rst files.

  • Google developer documentation style guide: Provides guidance on the writing style used for PyAnsys documentation.

  • Material for Sphinx: Provides guidance on authoring in reStructuredText when using Sphinx to generate documentation and includes a reStructuredText cheat sheet.

  • numpydoc Style guide: Provides the syntax and best practices for writing docstrings in PY files when the numpydoc extension for Sphinx is used. Docstrings describe Python modules, functions, classes, and methods. This guide’s overview also provides links to standard Python code conventions, additional PEPs (Python Enhancement Proposals) related to the documentation of code, and common code style checkers.

  • PEP 8 - Style Guide for Python Code: Provides guidance on the Python coding style that PyAnsys libraries use.

  • Python documentation: Provides the official documentation published by the Python organization for Python for developers at all levels.

  • Quick reStructuredText: Provides a summary of reStructuredText syntax with links to the reStructuredText Markup Specification for more comprehensive information.

  • reStructuredText Markup Specification: Provides a quick reStructuredText syntax overview, which explains that the parser is a component of Docutils, an open source text-processing system for plaintext documentation. It then provides the complete technical specification.

  • reStructuredText Markup Syntax and Parser Component of Docutils: Provides a description of reStructuredText and links to user, reference, and developer documentation, including a reStructuredText cheat sheet.

  • reStructuredText Primer: Provides introductory documentation on reStructuredText concepts and syntax as part of the documentation.

  • Style guide for Sphinx-based documentation: Provides coding standards for Sphinx-based documentation.

  • Using Markdown and Liquid in GitHub Docs: Provides an explanation of GitHub Flavored Markdown and explains how GitHub docs use Liquid syntax to expand the functionality to provide accessible tables, maintainable links, versioning, variables, and chunks of reusable content.

Tool resources#

The following alphabetized list of resources are for tools used in the writing and building of PyAnsys documentation.

  • Ansys Python Manager: Provides a cross-platform QT app for installing Python and managing your Python environment, including creating virtual environments, launching a command console, installing PyAnsys packages, and viewing PyAnsys documentation.

  • Ansys Sphinx Theme: Provides an Ansys-branded extension of the popular PyData Sphinx Theme that is used to generate PyAnsys documentation.

  • Ansys templates: Provides templates for creating PyAnsys projects that are compliant with PyAnsys guidelines.

  • Git: Provides a distributed version control system for tracking changes in source code during software development.

  • Git Extensions: Provides a GUI client for Git.

  • GitHub: Provides a web-based platform that uses Git as its underlying version control system but goes way beyond version control, offering a collaborative environment for hosting, managing, and sharing Git repositories.

  • GitHub Desktop: Provides a GUI client for Git.

  • Notepad++: Provides an open source code text and code editor for use on Microsoft Windows, supporting around 80 programming languages with syntax highlighting and code folding.

  • pip: Provides a package manager for installing Python packages from the Python Package Index (PyPI).

  • pre-commit: Provides for checking the conformance of your code against predefined code style conventions.

  • Python: Provides a general-purpose programming language that runs on almost all system architectures and is used for a wide range of applications in different fields.

  • Python in Visual Studio Code: Provides an extension that makes Visual Studio Code an excellent Python editor.

  • Sphinx: Provides a Python documentation generator for generating documentation from RST, MD, and PY files.

  • Vale: Provides for checking RST and MD files for consistent style and voice.

  • Visual Studio Code: Provides a lightweight but powerful source code editor that runs on your desktop and is available for WIndows , macOS, and Linux.

Note

For information on documentation style tools that might be implemented in a PyAnsys project but are not necessarily described on this page, see Documentation style tools.