描述

使用 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. Java基础知识笔记第一章:入门

    java的地位: java具有面向对象,与平台无关,安全,稳定和多线程等优良特性,是目前软件设计中优秀的编程语言. java的特点: 1.简单 2.面向对象 3.平台无关 jre(java runti ...

  2. python学习笔记(3) -- 字符与数字之间的转换函数

    转载:python中的字符数字之间的转换函数 int(x [,base ])         将x转换为一个整数     long(x [,base ])        将x转换为一个长整数     ...

  3. Codeforces Round #584 - Dasha Code Championship - Elimination Round (rated, open for everyone, Div. 1 + Div. 2)C

    #define HAVE_STRUCT_TIMESPEC#include<bits/stdc++.h>using namespace std;string s;pair<int,in ...

  4. 关于Android file.createNewFile() 方法出现的问题总结(转)

    原文:http://blog.csdn.net/wjdarwin/article/details/7108606 今天在编写向SDcard中,创建文件夹并向其中保存文件的过程中出现个一系列的问题 在此 ...

  5. 使用HttpURLConnection通过post请求服务器时,URLEncode编码的必要性

    通过Post提交表单数据时,数据类型为x-www-urlencoded,提交到服务器的数据服务器默认是通过URLEncoder.encode()编码过得,所以服务器处理时会用URLDecoder.de ...

  6. 「CH6201」走廊泼水节

    「CH6201」走廊泼水节 传送门 考虑 \(\text{Kruskal}\) 的过程以及用到一个最小生成树的性质即可. 在联通两个联通块时,我们肯定会选择最小的一条边来连接这两个联通块,那么这两个联 ...

  7. Centos7 mariadb (mysql)主从复制实现

    一.mysql基本命令 .启动mysql systemctl start mariadb .linux客户端连接自己 mysql -uroot -p -h 127.0.0.1 .远程链接mysql服务 ...

  8. UniGUI之Login窗口(10)

    在UniGUI的CHM帮助里读到的. 一定要新建一个其他空白的工程,然后再添加LoginForm LoginForm 是另一种特殊的表单类型, 仅用于登录目的. 此操作将创建一个与常规窗体外观相同的空 ...

  9. 用C语言写一个Helloworld_实现第一步编译运行

    编写第一个hello world 创建helloworld.c // 程序头文件 #include <stdio.h> // 主入口函数 int main(int arc, char* a ...

  10. Java程序基本优化

    1.尽量指定类的final修饰符,因为带有final修饰符的类是不可派生的. 2.尽量重用对象. 3.尽量使用局部变量. 4.不要重复初始化变量. 5.在Java+Oracle的应用系统开发中,Jav ...