【python学习过程--day2】python注释及生成对应的操作文档

python注释

        Python中有两种主要的注释方式：

1. 单行注释：使用#符号来注释单行代码。注释的内容直到行末都会被解释器忽略。

   # 这是一个单行注释 print("Hello, World!") # 这是另一个单行注释

2. 多行注释：使用三重引号 ''' 或 """ 来注释多行代码块。虽然在Python中没有多行注释的官方语法，但多行字符串文本可以实现类似的效果

           """ 这是一个多行注释。
   
           它可以用于注释多行代码块。 """
   
           print("Hello, World!")
   
   
           ''' 这是一个多行注释。
   
           它可以用于注释多行代码块。 '''
   
           print("Hello, World!")

        注释在编程中非常重要，可以帮助其他开发者理解代码的作用，也可以帮助自己在日后回顾代码时快速理解。良好的注释习惯是编程中的一个好习惯。

注释可以生成操作文档吗？

        是的，适当的注释可以帮助生成操作文档或者API文档。通常情况下，生成操作文档的过程是通过提取源代码中的注释信息并将其转换成可读的文档格式。这些文档可以包括函数、类、模块等的说明，以及参数、返回值、异常处理等方面的描述。

在Python中，常用的工具包括：

1. Sphinx：Sphinx是一个广泛用于生成Python项目文档的工具。它可以从源代码中的注释提取信息，并生成各种格式的文档，如HTML、PDF等。Sphinx支持reStructuredText和Markdown等格式的注释文档。

2. Doxygen：虽然Doxygen是一个C++为主的工具，但它也可以用于Python和其他编程语言的文档生成。它可以从源代码中提取注释信息，并生成HTML、PDF等格式的文档。

3. Pydoc：是一个用于Python项目的文档生成工具，但也可以应用于其他语言。它可以从源代码中提取注释信息，并生成HTML文档。

        这些工具通常会根据一定的规范和标记来解析注释，并将其转换成文档。因此，在编写代码时，遵循一定的注释规范和风格是非常重要的，这样可以确保生成的文档准确和易读。

 

注释生成操作文档的实例

        新建了一个py文件叫做utils.py，进入testpydoc.py所在目录

        python3 -m pydoc -w utils

        会默认将当前目录下的testpydoc生成一个叫做testpydoc.html的文档，如果是目录直接【python3 -m pydoc -w 目录名】生成文档

        点开查看： 

        说明：如果是将整个目录生成这种格式，不建议用这种方式，因为如果他展示目录下的子文件的说明时，会去子目录下找对应.html文件，如果文件不存在，就会404

        当然，要生成与Python文件对应的操作文档，你可以使用Sphinx工具，只是这个相对于pydoc来说操作更麻烦，但是可DIY性却更强。以下是一个简单的步骤：

1. 安装Sphinx：如果你还没有安装Sphinx，你可以使用pip来安装：

   pip install sphinx

2. 初始化Sphinx项目：在项目根目录下打开命令行，并执行以下命令初始化Sphinx项目：

   sphinx-quickstart

   这个命令会引导你设置一些选项，如文档目录、语言、作者等。你可以根据自己的需要进行设置。

3. 配置Sphinx：在初始化完成后，你可以编辑生成的conf.py文件来配置Sphinx的选项，如添加你的Python文件路径到extensions列表中：

   extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', # 其他扩展... ]

   这样就启用了自动文档生成和使用Google风格的注释。

4. 编写文档：在Sphinx项目的docs/source目录下，你可以创建.rst或者.md格式的文件，并使用reStructuredText或Markdown语法编写文档。

5. 生成文档：在命令行中执行以下命令来生成文档：

   sphinx-build -b html sourcedir builddir

   其中sourcedir是你存放文档源文件的目录，builddir是你想要生成文档的目录。

6. 查看文档：生成文档后，你可以在浏览器中打开生成的HTML文档来查看你的文档。

        通过这些步骤，你就可以生成与你的Python文件对应的操作文档了。你可以在文档中使用Sphinx提供的自动文档生成功能来生成函数、类、模块等的说明，也可以手动编写其他文档内容。

 

 

相关链接

Python编程：使用pydoc生成文档注释_python doc 注释-CSDN博客文章浏览阅读1w次，点赞5次，收藏17次。pydoc是python自带的一个文档生成工具，可以提取注释如果有三个引号的注释方法，会优先使用三个点的注释，其次才展示#号的注释示例使用的代码pydoc_demo.py，包含一个函数，一个类# -*- coding: utf-8 -*-# @Date : 2018-10-30# @Author : Peng Shiyu"""这个文档注释pydoc的示例"""# 函..._python doc 注释https://blog.csdn.net/mouday/article/details/83540541 pycharm 自动生成文件注释和函数注释_pycharm自动生成函数注释-CSDN博客文章浏览阅读5.7k次，点赞2次，收藏9次。1. 文件注释pycharm提供了一个在新建文件自动生成文件头注释的功能，可以实现自动生成运行环境，作者、日期等必要信息，使用比较方便，配置十分简单。在anaconda 的spider也有类似的功能，按照1-5的路径选项即可。在5中填写想要的注释。#!/usr/bin/env python# -*- encoding: utf-8 -*-"""@Modify Time @Author @Version @Desciption------------ _pycharm自动生成函数注释https://blog.csdn.net/qingfengxd1/article/details/106897060

 pydoc用法https://www.cnblogs.com/meitian/p/6704488.html

在 Sphinx 中描述代码 — Sphinx documentationhttps://daobook.github.io/sphinx/tutorial/describing-code.html 

完结撒花 

        我告诉自己不要想起你，但是我不知道我会那么的不听话