sphinx python_如何使用Sphinx记录Python代码

sphinx python

Python代码可以在其源代码中包含文档。 这样做的默认方式取决于docstrings ，它以三引号格式定义。 尽管文档的价值是有据可查的，但似乎似乎太普遍了，以至于没有足够的文档代码。 让我们来看一个关于强大文档功能的场景。

在进行了太多的白板技术采访，要求您实施斐波那契数列之后，您已经受够了。 您回家并用Python编写了一个可重用的斐波那契计算器，该计算器使用浮点数技巧获得了O（1）。

代码很简单：

   
   

    
    
 
     
     # fib.py 
     
     


     
     import 
     
     math 
     
     


     
     

_SQRT_5 
     
     = 
     
     math . 
     
     sqrt 
     
     ( 
     
     5 
     
     ) 
     
     

_PHI 
     
     = 
     
     ( 
     
     1 + _SQRT_5 
     
     ) / 
     
     2 
     
     


     
     


     
     def approx_fib 
     
     ( n 
     
     ) :
     
     

    
     
     return 
     
     round 
     
     ( _PHI** 
     
     ( n+ 
     
     1 
     
     ) / _SQRT_5 
     
     ) 
    
    
   
   

（斐波那契数列是四舍五入到最接近的整数的几何序列，这是我最喜欢的鲜为人知的数学事实之一。）

作为一个体面的人，您可以将代码开源，并将其放在PyPI上 。 setup.py文件非常简单：

   
   

    
    
 
     
     import setuptools
     
     


     
     

setuptools. 
     
     setup 
     
     ( 
     
     

    name 
     
     = 
     
     'fib' 
     
     , 
     
     

    version 
     
     = 
     
     '2019.1.0' 
     
     , 
     
     

    description 
     
     = 
     
     'Fibonacci' 
     
     , 
     
     

    py_modules 
     
     = 
     
     [ 
     
     "fib" 
     
     ] 
     
     , 
     
     


     
     ) 
    
    
   
   

但是，没有文档的代码是没有用的。 因此，您可以向函数添加文档字符串。 我最喜欢的文档字符串样式之一是“ Google”样式 。 标记很轻巧，当它位于源代码中时很好。

   
   

    
    
 
     
     def approx_fib 
     
     ( n 
     
     ) :
     
     

    
     
     """

    Approximate Fibonacci sequence



    Args:

        n (int): The place in Fibonacci sequence to approximate



    Returns:

        float: The approximate value in Fibonacci sequence

    """ 
     
     

    
     
     # ... 
    
    
   
   

但是函数的文档只是成功的一半。 散文文档对于上下文化代码用法很重要。 在这种情况下，背景是令人讨厌的技术采访。

有一个添加更多文档的选项，Pythonic模式是使用通常在docs /目录下添加的rst文件（ reStructuredText的缩写）。 因此， docs / index.rst文件最终看起来像这样：

   
   

    
    

     
     Fibonacci
     
     

=========
     
     


     
     

Are you annoyed at tech interviewers asking you to implement
     
     

the Fibonacci sequence?
     
     

Do you want to have some fun with them?
     
     

A simple
     
     

:code:`pip install fib`
     
     

is all it takes to tell them to,
     
     

um,
     
     

fib off.
     
     


     
     

.. automodule:: fib
     
     

   :members:
    
    
   
   

我们完成了，对吗？ 我们将文本存储在文件中。 有人应该看看。

使Python文档更漂亮

为了使您的文档看起来更漂亮，您可以利用Sphinx ，它旨在制作漂亮的Python文档。 这三个Sphinx扩展特别有用：

• sphinx.ext.autodoc ：从模块内部获取文档
• sphinx.ext.napoleon ：支持Google样式的文档字符串
• sphinx.ext.viewcode ：将ReStructured Text源与生成的文档打包在一起

为了告诉Sphinx什么以及如何生成，我们在docs / conf.py中配置一个辅助文件：

   
   

    
    

     
     extensions 
     
     = 
     
     [ 
     
     

    
     
     'sphinx.ext.autodoc' 
     
     , 
     
     

    
     
     'sphinx.ext.napoleon' 
     
     , 
     
     

    
     
     'sphinx.ext.viewcode' 
     
     , 
     
     


     
     ] 
     
     


     
     # The name of the entry point, without the ".rst" extension. 
     
     


     
     # By convention this will be "index" 
     
     

master_doc 
     
     = 
     
     "index" 
     
     


     
     # This values are all used in the generated documentation. 
     
     


     
     # Usually, the release and version are the same, 
     
     


     
     # but sometimes we want to have the release have an "rc" tag. 
     
     

project 
     
     = 
     
     "Fib" 
     
     

copyright 
     
     = 
     
     "2019, Moshe Zadka" 
     
     

author 
     
     = 
     
     "Moshe Zadka" 
     
     

version 
     
     = release 
     
     = 
     
     "2019.1.0" 
    
    
   
   

该文件使我们可以使用所需的所有元数据发布代码，并注意扩展名（上面的注释说明了如何）。 最后，要确切记录我们希望如何生成文档，请使用Tox来管理虚拟环境，以确保我们顺利生成文档：

   
   

    
    
 
     
     [ tox 
     
     ] 
     
     


     
     # By default, .tox is the directory. 
     
     


     
     # Putting it in a non-dot file allows opening the generated 
     
     


     
     # documentation from file managers or browser open dialogs 
     
     


     
     # that will sometimes hide dot files. 
     
     

toxworkdir 
     
     = 
     
     { toxinidir 
     
     } /build/tox
     
     


     
     


     
     [ testenv:docs 
     
     ] 
     
     


     
     # Running sphinx from inside the "docs" directory 
     
     


     
     # ensures it will not pick up any stray files that might 
     
     


     
     # get into a virtual environment under the top-level directory 
     
     


     
     # or other artifacts under build/ 
     
     

changedir 
     
     = docs
     
     


     
     # The only dependency is sphinx 
     
     


     
     # If we were using extensions packaged separately, 
     
     


     
     # we would specify them here. 
     
     


     
     # A better practice is to specify a specific version of sphinx. 
     
     

deps 
     
     = 
     
     

    sphinx
     
     


     
     # This is the sphinx command to generate HTML. 
     
     


     
     # In other circumstances, we might want to generate a PDF or an ebook 
     
     


     
     commands 
     
     = 
     
     

    sphinx-build -W -b html -d 
     
     { envtmpdir 
     
     } /doctrees . 
     
     { envtmpdir 
     
     } /html
     
     


     
     # We use Python 3.7. Tox sometimes tries to autodetect it based on the name of 
     
     


     
     # the testenv, but "docs" does not give useful clues so we have to be explicit. 
     
     

basepython 
     
     = python3.7
    
    
   
   

现在，无论何时运行Tox，它都会为您的Python代码生成漂亮的文档。

Python文档非常出色

docstrings ，添加.rst文件，然后添加Sphinx和Tox为用户美化结果。

您对好的文档有何评价？ 您还有其他喜欢的战术吗？ 在评论中分享他们！

翻译自: https://opensource.com/article/19/11/document-python-sphinx

sphinx python