Document writing
We use Sphinx to generate our documentation.
And if you want to contribute to our documentation, you can follow the steps below.
Install and Build
Install dependencies
cd docs pip install -r requirements.txt
Build documentation
cd docs make all-html
or run this command in CALYPSO package root.
make manual
Syntax
User Documents
We use MyST-Parser to write our documentation. If you want to write a document for user. You should check the syntax of MyST-Parser before writing.
API Documents
We use numpydoc to automatically generate api documentation. Only write numpydoc string in your codes and obey numpydoc style.
A example
class myClass:
"""
This is a simple example class
Parameters
----------
name : str
My name
age : int
My age
Arguments
---------
next_age : int
My age next year
Notes
-----
It's not necessary to write method docstring in class.
But you can write it if you want.
"""
def __init__(self, name: str, age: int):
self.name = name
self.age = age
def myMethod(self, arg1: int, arg2: str = "Default"):
"""A method to demonstrate the class method
Parameters
----------
arg1 : int
argument 1
arg2 : str, optional
argument 2, by default "Default"
"""
print("My name is", self.name)
print("I am", self.age, "years old")
self.next_age = self.age + 1
print("Next year I will be", self.next_age, "years old!")
print("You can use", arg1, "or", arg2, "arguments in myMethod!")
print("I am just a simple example class!")
Tool
vscode extension: MyST-Markdown vscode extension: autoDocstring