东莞网站建设报价 一呼百应,vs 团队网站开发,长沙官网seo技巧,狠狠做新网站sphinx简介sphinx是一种基于Python的文档工具#xff0c;它可以令人轻松的撰写出清晰且优美的文档#xff0c;由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的#xff0c;并且它已成为Python项目首选的文档工具#xff0c;同时它对C/C项目也有很好的…sphinx简介sphinx是一种基于Python的文档工具它可以令人轻松的撰写出清晰且优美的文档由Georg Brandl在BSD许可证下开发。新版的Python3文档就是由sphinx生成的并且它已成为Python项目首选的文档工具同时它对C/C项目也有很好的支持。更多详细特性请参考spinx官方文档本篇博客主要介绍如何快速为你的Python注释生成API文档。 环境需要安装python安装sphinxpip install sphinx1实例新建一个项目 目录结构如上图所示doc目录使用来存放API文档src目录是用来存放项目的源码。src目录下的源码#codingUTF-8class Demo1(): 类的功能说明 def add(self,a,b): 两个数字相加并返回结果 return ab def google_style(arg1, arg2): 函数功能. 函数功能说明. Args: arg1 (int): arg1的参数说明 arg2 (str): arg2的参数说明 Returns: bool: 返回值说明 return True def numpy_style(arg1, arg2): 函数功能. 函数功能说明. Parameters ---------- arg1 : int arg1的参数说明 arg2 : str arg2的参数说明 Returns ------- bool 返回值说明 return True123456789101112131415161718192021222324252627282930313233343536373839404142demo1文件主要使用了两种不同的Python注释分格。对于简单的例子和简单的函数以及文档说明使用google style显得更为简洁而对于比较复杂详细的文档说明numpy style更为流行。 #codingUTF-8 def my_function(a, b): 函数功能说明 my_function(2, 3) 6 my_function(a, 3) aaa return a * b123456789101112demo2文件的注释看起来像Python命令行输入的文档字符串主要是用来检查命令输出是否匹配下行的内容它允许开发人员在源码中嵌入真实的示例和函数的用法还能确保代码被测试和工作。 使用sphinx建立API文档项目进入到doc目录下cd 项目路径/doc1输入sphinx-quickstart命令会输出选项 Root path for the documentation [.]: sphinx_demo Separate source and build directories (y/n) [n]: y Name prefix for templates and static dir [_]: Project name: sphinx_demo Author name(s): sphinx demo Project version []: 1.0 Project release [1.0]: Project language [en]: zh_CN Source file suffix [.rst]: Name of your master document (without suffix) [index]: Do you want to use the epub builder (y/n) [n]: autodoc: automatically insert docstrings from modules (y/n) [n]: y doctest: automatically test code snippets in doctest blocks (y/n) [n]: y intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y todo: write todo entries that can be shown or hidden on build (y/n) [n]: y coverage: checks for documentation coverage (y/n) [n]: y imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y ifconfig: conditional inclusion of content based on config values (y/n) [n]: viewcode: include links to the source code of documented Python objects (y/n) [n]: githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: Create Makefile? (y/n) [y]: Create Windows command file? (y/n) [y]:1234567891011121314151617181920212223因为我们需要从Python代码的注释中自动导出API文档所以需要将autodoc: automatically insert docstrings from modules (y/n) [n]: y如果忘记设置可以在conf.py中的extensions中添加sphinx.ext.autodoc。选项后面没有输入的直接按回车键使用默认设置。选项后面有输入的按照我的设置即可如果不使用中文文档可以在language配置中使用默认设置。设置完成之后可以看到如下的目录结构 后面如果需要修改配置选项在source/conf.py文件中修改即可。 extensions [sphinx.ext.autodoc, sphinx.ext.doctest, sphinx.ext.intersphinx, sphinx.ext.todo, sphinx.ext.coverage, sphinx.ext.mathjax]123456通过设置conf.py中的extensions可以为sphinx添加额外的扩展如果想要将html文档转换为PDF只需要先安装扩展然后再此处添加即可使用。由于我们的注释代码主要同时支持google style和numpy style所以我们需要添加一个扩展来支持。 sphinx.ext.napoleon1为源码生成html文件修改source/conf.py文件的19-21行import osimport syssys.path.insert(0, os.path.abspath(../../../src))#指向src目录123将命令行切换到doc目录下执行以下命令sphinx-apidoc -o sphinx_demo/source ../src/Creating file sphinx_demo/source\demo1.rst.Creating file sphinx_demo/source\demo2.rst.Creating file sphinx_demo/source\modules.rst.1234清理文件cd sphinx_demomake cleanRemoving everything under build...123生成html文件make html1请确保这一步没有输出error和exception 打开build/html/index.html8. 修改API的主题打开source/conf.py文件找到html_theme alabaster修改即可sphinx官方提供了几种主题可以进行选择sphinx主题设置 相关错误解决办法SyntaxErrorNon-ASCII character \xba in file .....py在*.py文件的第一行添加#codingUTF-8 Encoding errorutf8 codec cant decode byte 0xc0 in position 44invalid start byte确保*.py文件的编码格式为utf-8通过notepad可以进行查看如果不是请修改为utf-8格式 添加sphinx.ext.napoleon后报Exception occurred ....return translator[sphinx].ugettext(message) KeyErrorsphinxSphinx1.3napoleon扩展使用sphinx.ext.napoleonSphinx 1.2使用sphinxcontrib.napoleon--------------------- 作者修炼之路 来源CSDN 原文https://blog.csdn.net/sinat_29957455/article/details/83657029 版权声明本文为博主原创文章转载请附上博文链接转载于:https://www.cnblogs.com/ExMan/p/10790285.html
