編今天學習java，學習了一種制作自己的API文檔的方法，制作的方法應該有好多，小編先把自己知道的這一種分享給大家。

我是在學習java的時候學到的，是在eclipse上制作的，下面就來一步一步的制作。

1. 先建一個java工程

2.雙擊工程-->右鍵src--> new --> Package（建立一個包）

3.在這個包內(nèi)建立一個類（右鍵test(包)--> new -->class）

4.然后就寫代碼，注意用(/** */)寫有關方法的注釋

5.準備工作就做完了，我們右鍵工程(Demo)-->Export...

這里是選擇你下載的jdk的安裝目錄中的bin的javadoc

6.選擇輸出的文件目錄就可以了

7.最后在文件目錄中點indec.html就是自己做的API文檔了

8.最后就是這樣了

小編也是剛學會的，大神們可能有更好的方法，這里只是分享一下，大神如果有跟好的方法，可以分享出來哦。

phinx簡介

sphinx是一種基于Python的文檔工具，它可以令人輕松的撰寫出清晰且優(yōu)美的文檔，由Georg Brandl在BSD許可證下開發(fā)。新版的Python3文檔就是由sphinx生成的，并且它已成為Python項目首選的文檔工具，同時它對C/C++項目也有很好的支持。更多詳細特性請參考spinx官方文檔，本篇博客主要介紹如何快速為你的Python注釋生成API文檔。

sphinx官方文檔鏈接：https://zh-sphinx-doc.readthedocs.io/en/latest/intro.html

環(huán)境

sphinx需要依賴Python環(huán)境，所以在使用sphinx之前需要先安裝Python

• 需要安裝python
• 安裝sphinx

pip install sphinx

實例

新建一個項目

目錄結構如上圖所示，doc目錄使用來存放API文檔，src目錄是用來存放項目的源碼。

src目錄下的源碼

#coding=UTF-8
class Demo1():
 """類的功能說明"""
 def add(self,a,b):
 """兩個數(shù)字相加，并返回結果"""
 return a+b
 def google_style(arg1, arg2):
 """函數(shù)功能.
 函數(shù)功能說明.
 Args:
 arg1 (int): arg1的參數(shù)說明
 arg2 (str): arg2的參數(shù)說明
 Returns:
 bool: 返回值說明
 """
 return True
 def numpy_style(arg1, arg2):
 """函數(shù)功能.
 函數(shù)功能說明.
 Parameters
 ----------
 arg1 : int
 arg1的參數(shù)說明
 arg2 : str
 arg2的參數(shù)說明
 Returns
 -------
 bool
 返回值說明
 """
 return True

demo1文件，主要使用了兩種不同的Python注釋分格。對于簡單的例子和簡單的函數(shù)以及文檔說明，使用google style顯得更為簡潔，而對于比較復雜詳細的文檔說明numpy style更為流行。

#coding=UTF-8
def my_function(a, b):
 """函數(shù)功能說明
 >>> my_function(2, 3)
 6
 >>> my_function('a', 3)
 'aaa'
 """
 return a * b

demo2文件的注釋看起來像Python命令行輸入的文檔字符串，主要是用來檢查命令輸出是否匹配下行的內(nèi)容，它允許開發(fā)人員在源碼中嵌入真實的示例和函數(shù)的用法，還能確保代碼被測試和工作。

使用sphinx建立API文檔項目

• 進入到doc目錄下

cd 項目路徑/doc

輸入sphinx-quickstart命令，會輸出選項

> Root path for the documentation [.]: sphinx_demo
> Separate source and build directories (y/n) [n]: y
> Name prefix for templates and static dir [_]:
> Project name: sphinx_demo
> Author name(s): sphinx demo
> Project version []: 1.0
> Project release [1.0]:
> Project language [en]: zh_CN
> Source file suffix [.rst]:
> Name of your master document (without suffix) [index]:
> Do you want to use the epub builder (y/n) [n]:
> autodoc: automatically insert docstrings from modules (y/n) [n]: y
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: y
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: y
> coverage: checks for documentation coverage (y/n) [n]: y
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: y
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: y
> ifconfig: conditional inclusion of content based on config values (y/n) [n]:
> viewcode: include links to the source code of documented Python objects (y/n) [n]:
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
> Create Makefile? (y/n) [y]:
> Create Windows command file? (y/n) [y]:

因為我們需要從Python代碼的注釋中自動導出API文檔，所以需要將autodoc: automatically insert docstrings from modules (y/n) [n]: y如果忘記設置，可以在conf.py中的extensions中添加'sphinx.ext.autodoc'。選項后面沒有輸入的，直接按回車鍵使用默認設置。選項后面有輸入的，按照我的設置即可，如果不使用中文文檔，可以在language配置中使用默認設置。設置完成之后，可以看到如下的目錄結構

后面如果需要修改配置，選項在source/conf.py文件中修改即可。

extensions = ['sphinx.ext.autodoc',
 'sphinx.ext.doctest',
 'sphinx.ext.intersphinx',
 'sphinx.ext.todo',
 'sphinx.ext.coverage',
 'sphinx.ext.mathjax']

通過設置conf.py中的extensions，可以為sphinx添加額外的擴展，如果想要將html文檔轉換為PDF，只需要先安裝擴展，然后再此處添加即可使用。由于我們的注釋代碼主要同時支持google style和numpy style，所以我們需要添加一個擴展來支持。

sphinx.ext.napoleon

為源碼生成html文件

• 修改source/conf.py文件的19-21行

import os
import sys
sys.path.insert(0, os.path.abspath('../../../src'))#指向src目錄

將命令行切換到doc目錄下，執(zhí)行以下命令

sphinx-apidoc -o sphinx_demo/source ../src/
>Creating file sphinx_demo/source\demo1.rst.
>Creating file sphinx_demo/source\demo2.rst.
>Creating file sphinx_demo/source\modules.rst.

清理文件

cd sphinx_demo
make clean
>Removing everything under 'build'...

生成html文件

make html

請確保這一步?jīng)]有輸出error和exception

打開build/html/index.html

修改API的主題

打開source/conf.py文件，找到html_theme = 'alabaster'，修改即可，sphinx官方提供了幾種主題可以進行選擇，sphinx主題設置

主題設置鏈接：http://www.sphinx-doc.org/en/master/theming.html

相關錯誤解決辦法

SyntaxError：Non-ASCII character '\xba' in file .....py

在*.py文件的第一行添加#coding=UTF-8

Encoding error：'utf8' codec can't decode byte 0xc0 in position 44：invalid start byte

確保*.py文件的編碼格式為utf-8，通過notepad++可以進行查看，如果不是請修改為utf-8格式

添加sphinx.ext.napoleon后報Exception occurred ....return translator['sphinx'].ugettext(message) KeyError：'sphinx'

Sphinx1.3，napoleon擴展使用sphinx.ext.napoleon，Sphinx <= 1.2使用sphinxcontrib.napoleon