Command Line

16. Comments and Autodoc

2020-03-25 08:00 CST
2020-03-25 23:25 CST
[![Creative Commons License](https://i.creativecommons.org/l/by-nc/4.0/88x31.png)](http://creativecommons.org/licenses/by-nc/4.0/)

注释风格

File Comments

Python

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# @Time    : ${DATE} ${TIME}
# @Author  : Shark
# @Site    : ${SITE}
# @File    : ${NAME}.py
# @Software: ${PRODUCT\_NAME}

C++

//
// @brief: 简单介绍
// @copyright: Copyright 2020 Google Inc
// @license: GPL
// @birth: created by Dablelv on 2018-08-02
// @version: V1.1.1
// @revision: last revised by lvlv on 2018-09-02
//

C++

Doxygen

/**
 *<A short one line description>
 *
 *<Longer description>
 *<May span multiple lines or paragraphs as needed>
 *
 *@param  <参数名> <参数说明>
 *@param  ...
 *@return <返回值说明>
 *@see    <相关函数>
 *@note   <注意>
 */

Python

Epytext: javadoc 风格

def docstring\_epytext(parm\_a, parm\_b, parm\_c):
    """
    Epytext Style

    @param parm\_a: this is a
    @type parm\_a: int
    @param parm\_b: this is b
    @type parm\_b: int
    @param parm\_c: this is c
    @type parm\_c: str
    @return: the result
    @raise keyError: raises an exception
    """

reST: Sphinx

def docstring\_restructruedtext(parm\_a: int, parm\_b: int, parm\_c: str) -> bool:
    """
    reStructed Style

    :param int parm\_a: this is a
    :param int parm\_b: this is b
    :param str parm\_c: this is c
    :return: the result
    :raises keyError: raises an exception
    :example:
        >>> my\_fuction(2, 3)
        6
        >>> my\_faction('a', 3)
        'aaa'

    :Author:  yourname
    :Create:  2020-03-04
    :Blog:    https://zhengzangw.com
    Copyright (c) 2020, All Rights Reserved.
    """

Google

def docstring\_google(parm\_a, parm\_b, parm\_c):
    """Summary here.

    Google Style long description

    Arg:
        parm\_a: int
            this is a
        parm\_b: this is b
        parm\_c: this is c

    Returns:
        The result

    Raises:
        KeyError: raises an exception
    """

class docstring\_google\_class(object):
    """Summary here

    Longer

    Attributes:
        attr\_1: this is attr 1
        attr\_2: this is attr 2
    """

Numpy

def docstring\_numpy(parm\_a, parm\_b, parm\_c):
    """
    Numpy Style

    Parameters
    ----------
    parm\_a (int): this is a
    parm\_b (str): this is b
    parm\_c (bool): this is c

    Returns
    -------
    this is result

Modifiers

TODO

// TODO(zhengzangw@gmail.com): Add comments to your code
// TODO(issue 12345): fix it

DEPRECATED

// DEPRECATED some comments

工具

sphinx

pip install sphinx
mkdir docs && cd docs
sphinx-quickstart
# Separate source and build directories
# Modify source/conf.py
sphinx-apidoc -o source ../src/
make html

Modify source/conf.py

  • import file

    import os
    import sys
    sys.path.insert(0, os.path.abspath('../../../src))
    
  • language: language='zh\_cn' 中文支持

  • theme: pip install sphinx-rtd-theme

    import sphinx\_rtd\_theme
    html\_theme = "sphinx\_rtd\_theme"
    html\_theme\_path = [sphinx\_rtd\_theme.get\_html\_theme\_path()]
    
  • extensions

    extensions = [
      'sphinx.ext.autodoc',
      'sphinx.ext.napoleon',  # Able to parse Numpy and Google
      'sphinx\_autodoc\_typehints', # pip install sphinx-autodoc-typehints
      'sphinx.ext.todo',
      'sphinx.ext.ifconfig',
      'sphinx.ext.mathjax',
      'recommonmark'
    ]
    napoleon\_use\_param = True
    
  • 中文 LaTeX

    latex\_engine = 'xelatex'
    latex\_elements = {
      # The paper size ('letterpaper' or 'a4paper').
      # 'papersize': 'letterpaper',
    
      # The font size ('10pt', '11pt' or '12pt').
      # 'pointsize': '10pt',
    
      # Additional stuff for the LaTeX preamble.
      'preamble': r'''
      \addto\captionsenglish{\renewcommand{\chaptername}{}}
      \usepackage[UTF8, scheme = plain]{ctex}
      \setCJKmainfont{STSongti-SC-Regular}
      ''',
    
      # Latex figure (float) alignment
      # 'figure\_align': 'htbp',
    }
    

reStructuredText

reStructuredText-Quick-Syntax

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   modules
   A file <test1.rst>
   test2
   c

.. code-block:: python
  :linenos:

  import project  
  # Get your stuff done
  project.do\_stuff()