# sphinx-demo

**Repository Path**: LvYanGGIT/sphinx-demo

## Basic Information

- **Project Name**: sphinx-demo
- **Description**: python  doc文件生成工具
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-04-22
- **Last Updated**: 2021-04-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

##python sphinx demo 
   一个doc文件生成的工具
###sphinx 相关 install 
### make 安装（Windows）
    https://sourceforge.net/projects/mingw-w64/files/Toolchains%20targetting%20Win64/Personal%20Builds/mingw-builds/8.1.0/threads-posix/seh/x86_64-8.1.0-release-posix-seh-rt_v6-rev0.7z
    解压
    输入 mingw-get install mingw32-make
    输入 mingw32-make
    mingw32-make: *** No targets specified and no makefile found.  Stop.
    说明已经安装成功。
    mingw32-make 改成 make
    环境变量配置
###文档相关生成
  ####安装：
       pip install sphinx -i https://pypi.doubanio.com/simple --trusted-host pypi.doubanio.com
       pip install sphinx sphinx-autobuild sphinx_rtd_theme recommonmark sphinx-markdown-tables
       pip install sphinx-markdown-tables
  ####配置shpinx
        $ cd myproject/doc
        $ sphinx-quickstart
   ####完成之后，会在当前目录创建 doc 目录，所有sphinx相关的文件都在 doc目录下。
         $ ls doc/
        _build  conf.py  index.rst  Makefile  _static  _templates
        $ vi doc/conf.py  #修改文件内容
        sys.path.insert(0, os.path.abspath('.'))
        sys.path.insert(0, os.path.abspath('..')) #　缺少此行会导致在make html时提示 __import__出错，找不到module。 所以必须把上一级目录(即代码所在目录)include进来
        sphinx-apidoc -o source/source ../src/
        sphinx-apidoc -o source/source/* ../src/*
extensions = ['sphinx.ext.autodoc',
    'sphinx.ext.doctest',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.mathjax',
    'sphinx_markdown_tables'
              ]

pdf  sphinx.ext.napoleon
        $ sphinx-apidoc -o doc/ ../src
        Creating file doc/a.rst.
        Creating file doc/modules.rst

        # 把生成的 doc/modules.rst添加到index.rst
        $ vi doc/index.rst

        Contents:
         .. toctree::
            :maxdepth: 2

            modules.rst
       生成html页面
        $ cd doc
        $ make html
   #####报错解决
     sphinx对仅工作在python2.7 或python3上。当文件中有中文时，可能会报错：'ascii' codec can't decode byte 0xe2 in position xxx。可以在报错的地方加入
     import sys
     reload(sys)
     sys.setdefaultencoding('utf-8')
其它项都选择默认
####author ： lvyang [952835607@qq.com]