diff --git a/doc/source/api/csst_proto.rst b/doc/source/api/csst_proto.rst index 1e73d515718df0d7b566c82bbe8a814a7688f16c..cdfced7bf2b224830748a1fa3c6d0063270c4767 100644 --- a/doc/source/api/csst_proto.rst +++ b/doc/source/api/csst_proto.rst @@ -2,6 +2,7 @@ API === .. automodule:: csst_proto.top_level_interface + :noindex: :members: :undoc-members: :show-inheritance: diff --git a/doc/source/codestyle.rst b/doc/source/codestyle.rst index b57903f708fbfe76ca2957107472f646ab40ca42..2a1326b8751a3cddf2428c9295114d876a5a50ae 100644 --- a/doc/source/codestyle.rst +++ b/doc/source/codestyle.rst @@ -39,9 +39,23 @@ Files/directories with asterisks (*) marks are optional. Code Style ========== Python code should follow PEP 8 - - https://peps.python.org/pep-0008/ + +- https://peps.python.org/pep-0008/ + Whereas C/C++ code should follow PEP 7 - - https://peps.python.org/pep-0007/ + +- https://peps.python.org/pep-0007/ + +Many IDEs (Pycharm, etc) and tools can be used to validate code style + +- pycodestyle: + - https://pycodestyle.pycqa.org/en/latest/ + +In our case, we recommend the following method to check code style + +.. code-block:: bash + + pycodestyle ./**/*.py --ignore=E121,E123,E126,E226,E24,E704,W503,W504,E501,E722 Numpy-style docstring @@ -50,9 +64,24 @@ There are several popular docstring styles, namely Google, reStructuredText, and The CSST DAS adopts Numpydoc-style among the three. We refer our developers to the Numpydoc official style guide for instructions on how to write docstrings. - - https://numpydoc.readthedocs.io/en/latest/format.html + +- https://numpydoc.readthedocs.io/en/latest/format.html + In particular, a complete example is available here. - - https://numpydoc.readthedocs.io/en/latest/example.html + +- https://numpydoc.readthedocs.io/en/latest/example.html + +In our case, we recommend the following method to check docstring + +.. code-block:: bash + + python -m numpydoc --validate {YOUR_PACKAGE}.top_level_interface.{YOUR_FUNCTION/CLASS} + +For example, + +.. code-block:: bash + + python -m numpydoc --validate csst_proto.top_level_interface.flip_image Markup language