Good API documentation drives library adoption and usage and is the foundation for a good developer experience. Even with the best interfaces and the most functional product, an API is not adopted if users aren’t satisfied with the documentation or the examples that they are presented with.
Good API documentation provides:
Increased adoption and improved experiences for developers using the API or library.
Reduction in the time spent on-boarding new contributors and users of the library.
Better maintenance of the code base. The time spent reading the source is often orders of magnitude greater than the time spent writing it. Well documented code (both in user-facing docstrings and developer comments) pays dividends in code maintenance.
Reduction in the amount of time spent understanding the API features.
The documentation for a PyAnsys library should contain:
Module, class, method, and function docstrings. See Docstrings.
Full gallery of examples. See PyMAPDL Examples.
General content on installing, using, and contributing.
Link to the library’s documentation from the repository’s README file.
To ensure clear and consistent documentation, all PyAnsys libraries are to follow the guidelines in the Google developer documentation style guide. Key guidelines include using:
Sentence case for headings and titles
Short, clear sentences
Finally, the documentation should be public and hosted via gh-pages, either as
a branch named
gh-pages within the library repository or within a
gh-pages branch within
For guidelines on how to acquire a specific DNS for hosting your documentation, see DNS configuration. You should ensure that you are compliant with the naming convention for your CNAME.