updated csster.rst

doc/source/csster.rst

@@ -63,49 +63,52 @@ An example: the docstring of numpy.cos()
         Traceback (most recent call last):
           File "<stdin>", line 1, in <module>
         ValueError: operands could not be broadcast together with shapes (3,3) (2,2)
-        Class docstring:
-        Functions that operate element by element on whole arrays.
-        To see the documentation for a specific ufunc, use `info`.  For
-        example, ``np.info(np.sin)``.  Because ufuncs are written in C
-        (for speed) and linked into Python with NumPy's ufunc facility,
-        Python's help() function finds this page whenever help() is called
-        on a ufunc.
-        A detailed explanation of ufuncs can be found in the docs for :ref:`ufuncs`.
-        **Calling ufuncs:** ``op(*x[, out], where=True, **kwargs)``
-        Apply `op` to the arguments `*x` elementwise, broadcasting the arguments.
-        The broadcasting rules are:
-        * Dimensions of length 1 may be prepended to either array.
-        * Arrays may be repeated along dimensions of length 1.
+
+        """
+
+
+We recommend our developers to follow the two examples below:
+
+If this function will be extensively used by other users, it should be documented in details.
+
+.. code-block:: python
+
+    def do_something(a, *args, **kwargs):
+        """ do something
 
         Parameters
         ----------
-        *x : array_like
-            Input arrays.
-        out : ndarray, None, or tuple of ndarray and None, optional
-            Alternate array object(s) in which to put the result; if provided, it
-            must have a shape that the inputs broadcast to. A tuple of arrays
-            (possible only as a keyword argument) must have length equal to the
-            number of outputs; use None for uninitialized outputs to be
-            allocated by the ufunc.
-        where : array_like, optional
-            This condition is broadcast over the input. At locations where the
-            condition is True, the `out` array will be set to the ufunc result.
-            Elsewhere, the `out` array will retain its original value.
-            Note that if an uninitialized `out` array is created via the default
-            ``out=None``, locations within it where the condition is False will
-            remain uninitialized.
-        **kwargs
-            For other keyword-only arguments, see the :ref:`ufunc docs <ufuncs.kwargs>`.
+        a : int
+            something
+        *args :
+            something
+        **kwargs :
+            other things
 
         Returns
         -------
-        r : ndarray or tuple of ndarray
-            `r` will have the shape that the arrays in `x` broadcast to; if `out` is
-            provided, it will be returned. If not, `r` will be allocated and
-            may contain uninitialized values. If the function has more than one
-            output, then the result will be a tuple of arrays.
+        b : float
+            speed of light
+
+        Examples
+        --------
+        >>> from csst import do_something
+        >>> do_something(3.1415926)
 
         """
+        pass
+
+
+If this function is only used by developers, it could be documented in short.
+
+.. code-block:: python
+
+    def do_something(a, *args, **kwargs):
+        """ do something """
+        pass
+
+
+
 
 
 TODOs

doc/source/index.rst

 csst
 ====
 
+.. meta::
+   :description lang=cn: Automate building, versioning, and hosting of your technical documentation continuously on Read the Docs.
+
+
 .. image:: https://readthedocs.org/projects/csst/badge/?version=latest
     :target: https://csst.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
@@ -10,10 +14,8 @@ csst
 * Github: https://github.com/csster/csst
 * PYPI: https://pypi.org/project/csst
 
-Installation
-------------
 
-Install using `pip <https://pypi.org/project/matplotlib>`__:
+Install using `pip <https://pypi.org/project/pip>`__:
 
    .. code-block:: bash
 
@@ -26,9 +28,12 @@ or
        pip install -U csst
 
 
+How to contribute
+-----------------
+
 .. toctree::
    :hidden:
-   :caption: DEVELOPMENT
+   :caption: How-to guides
    :maxdepth: 2
 
    csster
@@ -36,6 +41,9 @@ or
    contributors
 
 
+Examples
+--------
+
 .. toctree::
    :hidden:
    :caption: Examples
@@ -44,6 +52,9 @@ or
    tutorial
 
 
+API
+---
+
 .. toctree::
    :hidden:
    :maxdepth: 2