自动生成文档注释 sphinx支持从python源代码中提取文档注释信息,然后生成文档,我们将这称之为autodoc。 为了使用autodoc,首先需要在配置文件的extensions选项中添加'sphinx.ext.autodoc'。然后我们就可以使用autodoc的指令了。 只需要在rst文件中添加如下语句: .. autofunction:: io.open 也可以直接生成整个类的文档: .. automodule:: io :members: 为了提取文档注释,autodoc
这三个Sphinx扩展特别有用: sphinx.ext.autodoc :从模块内部获取文档 sphinx.ext.napoleon :支持Google样式的文档字符串 sphinx.ext.viewcode ReStructured Text源与生成的文档打包在一起 为了告诉Sphinx什么以及如何生成,我们在docs / conf.py中配置一个辅助文件: extensions = [ 'sphinx.ext.autodoc
可阅读在线文档,地址:http://robot-framework.readthedocs.io/en/3.0.2/autodoc/robot.api.html 编辑器?
考虑到文档编写、网站外貌(Sphinx很强大,但是他的autodoc功能导出的API文档在RTD主题下实在有点丑),最终选择了MkDocs+Markdown来编写文档。 但是这样又有了另外一个问题,MkDocs没有autodoc功能。如果手动编写,就意味着我要同时保持代码中的注释与API文档中的介绍一致。
[en]: zh_CN > Source file suffix [.rst]: > Name of your master document (without suffix) [index]: > autodoc
General configuration --------------------------------------------------- extensions = [ 'sphinx.ext.autodoc static'] html_logo = '_static/vllm-logo.png' html_favicon = '_static/favicon.ico' # -- Options for autodoc ---------------------------------------------------- autodoc_member_order = 'bysource' autodoc_default_options 环境) make latexpdf # 实时预览文档(自动重建) sphinx-autobuild source build/html 3.4 API 文档自动生成 vLLM 使用 Sphinx 的 autodoc
static drwxr-xr-x 2 dechin dechin 4096 2月 23 00:04 _templates 可以参考楼主的配置方案,这里我们主要是将主题配置成了rtd的格式,同时打开了autodoc ----------------------------------------------------- # If extensions (or modules to document with autodoc Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = ["sphinx_rtd_theme", "sphinx.ext.autodoc
Sphinx拓展功能 12345678910111213Please indicate if you want to use one of the following Sphinx extensions:> autodoc
还有很关键的一点是Sphinx有autodoc和automodule的扩展, 可以从代码中提取出文档,与代码直接进行关联。提供一个例子可以方便的在文档和源码中进行跳转。
package.extras] docs = ["furo (>=2023.08.17)", "sphinx (>=7.0,<8.0)", "sphinx-argparse-cli (>=1.5)", "sphinx-autodoc-typehints
# pip install sphinx # 创建Sphinx项目 # sphinx-quickstart # 配置conf.py extensions = [ 'sphinx.ext.autodoc elif metric == 'max': result[metric] = max(data) return result 使用Sphinx的autodoc
[pbr] # pbr本身的配置 warnerrors = True autodoc_tree_index_modules = True [entry_points] # 指定入口点 console_scripts
Flask-Autodoc - Documentation generator for flask Flask-NYC - New York Flask
-- Path setup -------------------------------------------------------------- # 如果需要在其他目录中使用扩展(或要使用autodoc extensions = [ "sphinx.ext.autodoc", "sphinx.ext.doctest", "sphinx.ext.intersphinx", sphinx.ext.napoleon", "sphinx.ext.linkcode" # "numpydoc", ] # 为了避免在read-the-docs构建过程中出现内存错误 autodoc_mock_imports file. epub_exclude_files = ["search.html"] # Set the order in which members are documented in the autodoc output autodoc_member_order = "bysource" # -- Extension configuration -----------------------------
为了生成文档,别名的名称会丢失(jax.lax.slice的HTML 文档将操作数报告为类型Any),因此文档的好处并未超出源代码(尽管我们可以启用一些sphinx-autodoc选项来改进此功能:参见 autodoc_type_aliases)。