安装

  1. pip install sphinx

使用

sphinx-quickstart

快速构建框架

  1. mkdir docs
  2. cd docs
  3. sphinx-quickstart  # 按提示输入

image.png
目录结构

  1. .
  2. ├── build
  3. ├── make.bat
  4. ├── Makefile
  5. └── source
  6.     ├── conf.py       # 配置文件
  7.     ├── index.rst     # 入口文件
  8.     ├── _static
  9.     └── _templates

修改配置文件

  1. import os
  2. import sys
  4. BASE_DIR = os.path.dirname(os.path.realpath(__file__))
  5. PKG_DIR = os.path.dirname(os.path.dirname(BASE_DIR))
  7. print(PKG_DIR)
  9. sys.path.insert(0, PKG_DIR)  # 添加docs上层目录到PYTHONPATH中，才可以搜索到上层目录的package
  11. # ...
  13. # 修改extensions
  14. extensions = [
  15.     'sphinx.ext.autodoc',
  16.     'sphinx.ext.coverage',
  17.     'sphinx.ext.intersphinx',
  18.     'sphinx.ext.viewcode',
  19. ]
  21. # 替换主题
  22. # html_theme = 'alabaster'
  23. html_theme = 'sphinx_rtd_theme'
  25. # 添加master_doc(否则Read the Docs构建时会报错)
  26. master_doc = 'index'

sphinx-apidoc

为上层目录的bam2html目录自动生成apidoc

  1. sphinx-apidoc -o source/api ../bam2html/

image.png

make

构建HTML

编辑index.rst

  1. .. bam2html documentation master file, created by
  2.    sphinx-quickstart on Fri Aug 28 14:33:06 2020.
  3.    You can adapt this file completely to your liking, but it should at least
  4.    contain the root `toctree` directive.
  6. ====================================
  7. Bam2HTML |version| Documentation
  8. ====================================
  9. Bam2HTML is a tool to generate highlighted html file from bam, which is based on
  10. the command `samtools tview`.
  13. API Reference
  14. =============
  15. .. toctree::
  16.    :caption: APIs
  17.    :hidden:
  19.    api/modules
  21. :doc:`api/modules`
  22.    The APIs of modules
  25. Indices and tables
  26. ==================
  27. * :ref:`genindex`
  28. * :ref:`modindex`
  1. make html

image.png
浏览器查看效果

  1. cd build/html
  3. python -m SimpleHTTPServer 8088

image.png