codestyle.rst

Code Structure
==============
An example code structure is shown below.
Files/directories with asterisks (*) marks are optional.

.. code-block::

    csst_proto                                # the repository name
    ├── csst_proto                            # the package name
    │   ├── data                              # package associated data directory
    │   ├── __init__.py                       # necessary file for a Python package
    │   ├── flip_image.py                     # Python modules
    │   ├── scratch.py
    │   ├── some_other_modules.py
    │   └── top_level_interface.py            # the top level interface module
    ├── doc                                   # *sphinx-based documentation directory
    │   ├── build
    │   ├── source
    │   ├── Makefile
    │   ├── apidoc.sh
    │   ├── contents.md
    │   ├── make.bat
    │   └── preview.sh
    ├── examples                              # *example scripts
    │   ├── how_this_code_will_be_used.py
    │   └── how_to_write_docstring.py
    ├── tests                                 # unit tests
    │   ├── test_flip_image.py
    │   └── test_other_functions.py
    ├── LICENSE                               # license file
    ├── README.md                             # README file (Markdown recommended)
    ├── install.sh                            # a single-line installation script
    ├── install_local.sh                      # local installation script
    ├── readthedocs.yml                       # *configuration file for readthedocs
    ├── requirements.txt                      # package dependencies
    └── setup.py                              # setup file


Code Style
==========
Python code should follow PEP 8

- https://peps.python.org/pep-0008/

Whereas C/C++ code should follow PEP 7

- 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
=====================
There are several popular docstring styles, namely Google, reStructuredText, and Numpy.
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

In particular, a complete example is available here.

- 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
===============
Markdown and reStructrured Text are two of popular markup languages.
reStructrured Text is used in Numpydoc docstrings as well as sphinx-based documentation.
Markdown is much easier and usually used to write `README` for a package.

- Markdown
    - https://www.markdownguide.org/
- reStructured Text
    - https://www.writethedocs.org/guide/writing/reStructuredText/