From e034b67130de6bfd41199391e3933ef21414fa42 Mon Sep 17 00:00:00 2001 From: kotfu Date: Sat, 22 Feb 2020 20:44:11 -0700 Subject: Clarify that the API documentation is the public API. --- docs/api/index.rst | 13 +++++++++++++ docs/overview/integrating.rst | 7 +++++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/docs/api/index.rst b/docs/api/index.rst index 5935e216..d5fc013b 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -1,6 +1,19 @@ API Reference ============= +These pages document the public API for ``cmd2``. If a method, class, function, +attribute, or constant is not documented here, consider it private and subject +to change. There are many classes, methods, functions, and constants in the +source code which do not begin with an underscore but are not documented here. +When looking at the source code for this library, you can not safely assume +that because something doesn't start with an underscore, it is a public API. + +If a release of this library changes any of the items documented here, the +version number will be incremented according to the `Semantic Version +Specification `_. + +This documentation is for version |version| of ``cmd2``. + .. toctree:: :maxdepth: 1 diff --git a/docs/overview/integrating.rst b/docs/overview/integrating.rst index 0cc7816e..db5cb206 100644 --- a/docs/overview/integrating.rst +++ b/docs/overview/integrating.rst @@ -10,8 +10,11 @@ include ``cmd2``. Make sure your ``setup.py`` includes the following:: The ``cmd2`` project uses `Semantic Versioning `_, which means that any incompatible API changes will be release with a new major -version number. We recommend that you follow the advice given by the Python -Packaging User Guide related to `install_requires +version number. The public API is documented in the :ref:`api/index:API +Reference`. + +We recommend that you follow the advice given by the Python Packaging User +Guide related to `install_requires `_. By setting an upper bound on the allowed version, you can ensure that your project does not inadvertently get installed with an incompatible future -- cgit v1.2.1