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/


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


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/