mirror of
https://github.com/LCTT/TranslateProject.git
synced 2025-01-22 23:00:57 +08:00
translating
This commit is contained in:
geekpi
parent
b0b9787024
commit
b7b59d781d
@ -1,180 +0,0 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to document Python code with Sphinx)
|
||||
[#]: via: (https://opensource.com/article/19/11/document-python-sphinx)
|
||||
[#]: author: (Moshe Zadka https://opensource.com/users/moshez)
|
||||
|
||||
How to document Python code with Sphinx
|
||||
======
|
||||
Documentation is best as part of the development process. Sphinx, along
|
||||
with Tox, makes it easy to write and beautiful to look at.
|
||||
![Python in a coffee cup.][1]
|
||||
|
||||
Python code can include documentation right inside its source code. The default way of doing so relies on **docstrings**, which are defined in a triple quote format. While the value of documentation is well... documented, it seems all too common to not document code sufficiently. Let's walk through a scenario on the power of great documentation.
|
||||
|
||||
After one too many whiteboard tech interviews that ask you to implement the Fibonacci sequence, you have had enough. You go home and write a reusable Fibonacci calculator in Python that uses floating-point tricks to get to O(1).
|
||||
|
||||
The code is pretty simple:
|
||||
|
||||
|
||||
```
|
||||
# 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)
|
||||
```
|
||||
|
||||
(That the Fibonacci sequence is a geometric sequence rounded to the nearest whole number is one of my favorite little-known math facts.)
|
||||
|
||||
Being a decent person, you make the code open source and put it on [PyPI][2]. The **setup.py** file is simple enough:
|
||||
|
||||
|
||||
```
|
||||
import setuptools
|
||||
|
||||
setuptools.setup(
|
||||
name='fib',
|
||||
version='2019.1.0',
|
||||
description='Fibonacci',
|
||||
py_modules=["fib"],
|
||||
)
|
||||
```
|
||||
|
||||
However, code without documentation is useless. So you add a docstring to the function. One of my favorite docstring styles is the ["Google" style][3]. It is light on markup, which is nice when it is inside the source code.
|
||||
|
||||
|
||||
```
|
||||
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
|
||||
"""
|
||||
# ...
|
||||
```
|
||||
|
||||
But the function's documentation is only half the battle. Prose documentation is important for contextualizing code usage. In this case, the context is annoying tech interviews.
|
||||
|
||||
There is an option to add more documentation, and the Pythonic pattern is to use an **rst** file (short for [reStructuredText][4]) commonly added under a **docs/** directory. So the **docs/index.rst** file ends up looking like this:
|
||||
|
||||
|
||||
```
|
||||
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:
|
||||
```
|
||||
|
||||
And we're done, right? We have the text in a file. Someone should look at it.
|
||||
|
||||
### Making Python documentation beautiful
|
||||
|
||||
To make your documentation look beautiful, you can take advantage of [Sphinx][5], which is designed to make pretty Python documents. In particular, these three Sphinx extensions are helpful:
|
||||
|
||||
* **sphinx.ext.autodoc**: Grabs documentation from inside modules
|
||||
* **sphinx.ext.napoleon**: Supports Google-style docstrings
|
||||
* **sphinx.ext.viewcode**: Packages the ReStructured Text sources with the generated docs
|
||||
|
||||
|
||||
|
||||
In order to tell Sphinx what and how to generate, we configure a helper file at **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"
|
||||
```
|
||||
|
||||
This file allows us to release our code with all the metadata we want and note our extensions (the comments above explain how). Finally, to document exactly how we want the documentation generated, use [Tox][6] to manage the virtual environment to make sure we generate the documentation smoothly:
|
||||
|
||||
|
||||
```
|
||||
[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
|
||||
```
|
||||
|
||||
Now, whenever you run Tox, it will generate beautiful documentation for your Python code.
|
||||
|
||||
### Documentation in Python is excellent
|
||||
|
||||
As a Python developer, the toolchain available to us is fantastic. We can start with **docstrings**, add **.rst** files, then add Sphinx and Tox to beautify the results for users.
|
||||
|
||||
What do you appreciate about good documentation? Do you have other favorite tactics? Share them in the comments!
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/19/11/document-python-sphinx
|
||||
|
||||
作者：[Moshe Zadka][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[译者ID](https://github.com/译者ID)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/moshez
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/coffee_python.jpg?itok=G04cSvp_ (Python in a coffee cup.)
|
||||
[2]: https://pypi.org/
|
||||
[3]: http://google.github.io/styleguide/pyguide.html#381-docstrings
|
||||
[4]: http://docutils.sourceforge.net/rst.html
|
||||
[5]: http://www.sphinx-doc.org/en/master/
|
||||
[6]: https://tox.readthedocs.io/en/latest/
|
||||
@ -0,0 +1,181 @@
|
||||
[#]: collector: (lujun9972)
|
||||
[#]: translator: (geekpi)
|
||||
[#]: reviewer: ( )
|
||||
[#]: publisher: ( )
|
||||
[#]: url: ( )
|
||||
[#]: subject: (How to document Python code with Sphinx)
|
||||
[#]: via: (https://opensource.com/article/19/11/document-python-sphinx)
|
||||
[#]: author: (Moshe Zadka https://opensource.com/users/moshez)
|
||||
|
||||
如何使用 Sphinx 给 Python 代码写文档
|
||||
======
|
||||
最好将文档作为开发过程的一部分。Sphinx 加上 Tox，让文档可以轻松书写，并且外观漂亮。
|
||||
![Python in a coffee cup.][1]
|
||||
|
||||
Python 代码可以在源码中包含文档。这种方式默认依靠 **docstring**，它以三引号格式定义。虽然文档的价值是很大的，但是代码没有充足的文档还是很常见。让我们演练一个场景，了解出色的文档的强大功能。
|
||||
|
||||
经历了太多白板技术面试，要求你实现斐波那契数列，你已经受够了。你回家用 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][2] 上。setup.py 文件很简单：
|
||||
|
||||
|
||||
```
|
||||
import setuptools
|
||||
|
||||
setuptools.setup(
|
||||
name='fib',
|
||||
version='2019.1.0',
|
||||
description='Fibonacci',
|
||||
py_modules=["fib"],
|
||||
)
|
||||
```
|
||||
|
||||
但是，没有文档的代码是没有用的。因此，你可以向函数添加 docstring。我最喜欢的 docstring 样式之一是 [“Google” 样式][3]。标记很轻量，这在它位于源代码中时很好。
|
||||
|
||||
|
||||
```
|
||||
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][4] 的缩写）。因此**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][5]，它旨在制作漂亮的 Python 文档。这三个 Sphinx 扩展特别有用：
|
||||
|
||||
* **sphinx.ext.autodoc**：从模块内部获取文档
|
||||
* **sphinx.ext.napoleon**：支持 Google 样式的 docstring
|
||||
* **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][6] 管理虚拟环境以确保我们顺利生成文档：
|
||||
|
||||
|
||||
```
|
||||
[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
|
||||
```
|
||||
|
||||
现在，无论何时运行T ox，它都会为你的 Python 代码生成漂亮的文档。
|
||||
|
||||
### 在 Python 中写文档很好
|
||||
|
||||
作为 Python 开发人员，我们可以使用的工具链很棒。 我们可以从 **docstring** 开始，添加 **.rst** 文件，然后添加 Sphinx 和 Tox 来为用户美化结果。
|
||||
|
||||
你对好的文档有何评价？ 你还有其他喜欢的方式么？ 请在评论中分享它们！
|
||||
|
||||
--------------------------------------------------------------------------------
|
||||
|
||||
via: https://opensource.com/article/19/11/document-python-sphinx
|
||||
|
||||
作者：[Moshe Zadka][a]
|
||||
选题：[lujun9972][b]
|
||||
译者：[geekpi](https://github.com/geekpi)
|
||||
校对：[校对者ID](https://github.com/校对者ID)
|
||||
|
||||
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
|
||||
|
||||
[a]: https://opensource.com/users/moshez
|
||||
[b]: https://github.com/lujun9972
|
||||
[1]: https://opensource.com/sites/default/files/styles/image-full-size/public/lead-images/coffee_python.jpg?itok=G04cSvp_ (Python in a coffee cup.)
|
||||
[2]: https://pypi.org/
|
||||
[3]: http://google.github.io/styleguide/pyguide.html#381-docstrings
|
||||
[4]: http://docutils.sourceforge.net/rst.html
|
||||
[5]: http://www.sphinx-doc.org/en/master/
|
||||
[6]: https://tox.readthedocs.io/en/latest/
|
||||
Loading…
Reference in New Issue
Block a user