描述

使用 pip 安装sphinx后,按照教程建立了一个新的py文件,如下

# run.py
def run(name):
"""
this is how we run
:param name name of people who runs
"""
print(name, 'is running')

随后新建一个目录,使用 sphinx-quickstart 新建了sphinx环境,此时目录结构如下:

- doc
- Makefile
- build/
- make.bat
- source/
- run.py

此时进入 source目录,在conf.py 中添加文件路径,如下:

import os
import sys
sys.path.insert(0, os.path.abspath('../..'))

然后在 doc 下执行下面命令:

make html

or

sphinx-build -b html ./doc/source ./doc/build

发现两个命令都可以正常生成文档的模版,但并没有生成注释;即有生成的html,但没有代码的注释/API文档

尝试解决

1

开始以往是版本不一致,就重新建了virtualenv,还是不行;

使用了一个docker镜像,重试,结果是同样的错误

2

尝试看非官方的教程,发现还需要更改 source 下的 index.rst;

例如我们的代码文件是 run.py ,需要把他加到 index.rst中,如下(run就是模块名称):

API
===
.. automodule:: run
:members:

再次执行,发现还有错,只不过提示不一样了:提示

Unknown directive type “automodule” or “autoclass”

3

谷歌之,发现还要改一个配置的地方;位于 conf.py 里,增加一个扩展……如下:

extensions = [
'sphinx.ext.autodoc'
]

此处参考了 https://stackoverflow.com/questions/13516404/sphinx-error-unknown-directive-type-automodule-or-autoclass

再次尝试,终于成功了…

感想……

也许是我文档看的不够细,但实在是感觉不太友好啊

Python Sphinx使用踩坑记录的更多相关文章

  1. python fc21~fc29踩坑记录

    最近在公司的linux fc21上安装python和anaconda, 直接mintmenu给挂掉了. 真是弱爆了. 后来,升级终于来了, 升到了fc29.好,再看看, python2.7还在, py ...

  2. python发布包到pypi的踩坑记录

    前言 突然想玩玩python了^_^ 这篇博文记录了我打算发布包到pypi的踩坑经历.python更新太快了,甚至连这种发布上传机制都在不断的更新,这导致网上的一些关于python发布上传到pypi的 ...

  3. CentOS7.4安装MySQL踩坑记录

    CentOS7.4安装MySQL踩坑记录 time: 2018.3.19 CentOS7.4安装MySQL时网上的文档虽然多但是不靠谱的也多, 可能因为版本与时间的问题, 所以记录下自己踩坑的过程, ...

  4. unionId突然不能获取的踩坑记录

    昨天(2016-2-2日),突然发现系统的一个微信接口使用不了了.后来经查发现,是在网页授权获取用户基本信息的时候,unionid获取失败导致的. 在网页授权获取用户基本信息的介绍中(http://m ...

  5. ubuntu 下安装docker 踩坑记录

    ubuntu 下安装docker 踩坑记录 # Setp : 移除旧版本Docker sudo apt-get remove docker docker-engine docker.io # Step ...

  6. SpringBoot + Shiro + shiro.ini 的踩坑记录

    0.写在前面的话 好久没写博客了,诶,好多时候偷懒直接就抓网上的资料丢笔记里了,也就没有自己提炼,偷懒偷懒.然后最近参加了一个网络课程,要交作业的那种,为了能方便看下其他同学的作业,就写了个爬虫把作业 ...

  7. 你真的了解字典(Dictionary)吗? C# Memory Cache 踩坑记录 .net 泛型 结构化CSS设计思维 WinForm POST上传与后台接收 高效实用的.NET开源项目 .net 笔试面试总结(3) .net 笔试面试总结(2) 依赖注入 C# RSA 加密 C#与Java AES 加密解密

    你真的了解字典(Dictionary)吗?   从一道亲身经历的面试题说起 半年前,我参加我现在所在公司的面试,面试官给了一道题,说有一个Y形的链表,知道起始节点,找出交叉节点.为了便于描述,我把上面 ...

  8. google nmt 实验踩坑记录

       最近因为要做一个title压缩的任务,所以调研了一些text summary的方法.    text summary 一般分为抽取式和生成式两种.前者一般是从原始的文本中抽取出重要的word o ...

  9. ABP框架踩坑记录

    ABP框架踩坑记录 ASP.NET Boilerplate是一个专用于现代Web应用程序的通用应用程序框架. 它使用了你已经熟悉的工具,并根据它们实现最佳实践. 文章目录 使用MySQL 配置User ...

随机推荐

  1. cmd常用小命令

    #设置n秒后自动关机 -a取消 shutdown -s -t n #输出内容到fileName里,如果文件不存在将会创建文件,>是替换,>>是追加echo something > ...

  2. Codeforces Round #594 (Div. 2) - C. Ivan the Fool and the Probability Theory(思维)

    题意:给n*m的网格涂黑白两种颜色,保证每个格子上下左右的四个格子中最多只有一个格子与自己颜色相同,问有多少种涂法?结果$mod1000000007$ 思路:先只考虑一行有多少种涂法 $dp[i][0 ...

  3. Mac安装navigate premium

    转自Navicat Premium for Mac v12.0.22.0 破解教程,macOS上手动破解,无需补丁,无毒今天换了电脑,想装一个Navicat,突然发现了这篇破解教程,竟爱不释手,顾Co ...

  4. mysql path妙用

    CREATE TABLE `lc_c_user_path` ( `id` INT ( ) UNSIGNED NOT NULL AUTO_INCREMENT, `user_id` VARCHAR ( ) ...

  5. 任意两点之间的最短路(floyed)

    F.Moving On Firdaws and Fatinah are living in a country with nn cities, numbered from 11 to nn. Each ...

  6. zabbix开启对中文的支持--&&--中文乱码解决方法

    zabbix不支持中文图 开启zabbix对中文的支持 原来zabbix默认把对中文的支持给关闭了,我们需要修改zabbix的php源文件. 修改站点根目录下include/locales.inc.p ...

  7. IDEA JSP中报错cannot resolve method println的解决方案

    原因是没有导入Tomcat 库, 在 Project structure 添加

  8. pwn之偏移量offset

    0x7fffffffdd00: 0x4141414141414141 0x4141414141414141 0x7fffffffdd10: 0x4141414141414141 0x414141414 ...

  9. Keras入门——(4)长短期记忆网络LSTM(一)

    参考: https://blog.csdn.net/zwqjoy/article/details/80493341 https://blog.csdn.net/u012735708/article/d ...

  10. Vue - 引入本地图片的两种方式

    第一种,只引入单个图片,这种引入方法在异步中引入则会报错. 比如需要遍历出很多图片展示时 <image :src = require('图片的路径') /> 第二种,可引入多个图片,也可引 ...