使用maven插件生成項目的api文檔

讀

在進行Java學習的時候，相信大家都看過在線或者下載的java api文檔，可能是html格式或者chm格式的，其實這些參考文檔也是很容易生成的，這里介紹一個maven的插件來實現項目代碼文檔的生成。

JDK 7 API

操作步驟

1. 在項目的pom.xml文件中，添加如下代碼：

<profiles>
<profile>
<id>doclint-java8-disable</id>
<activation>
<jdk>[1.8,)</jdk>
</activation>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<additionalparam>-Xdoclint:none</additionalparam>
</configuration>
</plugin>
</plugins>
</build>
</profile>
</profiles>

注意事項:

（1）jdk8以后的版本添加了doclint，這個工具會規范HTML文檔，對于不正確的嵌套，非法的html屬性，未關閉的標簽等，java doc就會生成失敗，所以一個臨時解決方案是將doclint在jdk8中disable掉（-Xdoclint:none）

（2）在拷貝上述配置到pom文件中時，注意標簽的嵌套。譬如：在已有項目中已經存在了profiles標簽，那么只需拷貝profile之間的內容即可

2. 使用maven命令生成java文檔

mvn javadoc:javadoc

生成文檔命令

控制臺日志輸出

3. 生成的html文檔，會散落在各個功能模塊的target/site/apidocs目錄下，雙擊index.html即可查看生成的文檔

生成的文檔

其他

1. 如果不喜歡看html格式的java文檔，可以到網上找工具將html合成chm格式的電子書，方便分發和攜帶

2. 如果在生成java文檔時，報出錯誤“編碼GBK的不可映射字符”，可以在pom.xml文件中設置編碼格式來解決：

<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<maven.compiler.encoding>UTF-8</maven.compiler.encoding>
</properties>

錄

技術背景

量子線路背景知識
自動化文檔生成的方案

安裝sphinx
基于python的量子線路打印小項目
sphinx文檔生成與效果一覽
補充說明（2021.03.27）
總結概要
版權聲明

技術背景

該文章一方面從量子線路的打印著手，介紹了一個簡單的python量子線路工程。同時基于這個簡單的小工程，我們順帶的介紹了python的API文檔自動化生成工具Sphinx的基本使用方法。

量子線路背景知識

在前面幾篇博客中，有介紹過使用開源量子計算編程框架ProjectQ進行量子線路的繪制，會給我們輸出一個tex格式的線路圖，在文章中可以直接使用。關于量子線路與量子邏輯門操作，在這篇博客中有比較初步的介紹。而本文章中所創建的工程，是直接在cmd窗口里面打印輸出字符串形式的量子線路，同樣的，在量子計算資源估計和量子線路工程中，可以產生一定的作用。

自動化文檔生成的方案

對于一個比較優雅的python開源項目來說，一份簡介的文檔是必不可少的。一般一個python項目的文檔有兩部分組成：一部分是用markdown撰寫的使用說明文檔，其宗旨在于概述的介紹整個項目的重點內容，以及可能包含少部分的使用示例。這部分的文檔可以先用markdown寫，然后通過一些開源工具，如mkdocs等轉換成read_the_docs格式的文檔。read_the_docs格式的文檔大概如下圖所示，也可以直接參考其官方文檔。而文檔的第二個部分則是具體到每個函數、每個類的接口文檔。在開發階段，我們先按照格式要求寫好注釋文檔，然后通過開源工具Sphinx就可以自動化的生成API接口文檔。

安裝sphinx

這里我們直接使用python的包管理工具pip來安裝Sphinx以及一個read_the_docs格式的python庫。如果不需要使用read_the_docs格式也可以不安裝后者，只是后者在python的開源項目中還是最常用的一種文檔格式，并且可以配合read_the_docs網站進行API文檔的托管，因此推薦使用。

[dechin@dechin-manjaro circuit]$ python3 -m pip install sphinx
Requirement already satisfied: sphinx in /home/dechin/anaconda3/lib/python3.8/site-packages (3.4.3)
Requirement already satisfied: sphinxcontrib-htmlhelp in /home/dechin/anaconda3/lib/python3.8/site-packages (from sphinx) (1.0.3)
Requirement already satisfied: docutils>=0.12 in /home/dechin/anaconda3/lib/python3.8/site-packages (from sphinx) (0.16)
Requirement already satisfied: idna<3,>=2.5 in /home/dechin/anaconda3/lib/python3.8/site-packages (from requests>=2.5.0->sphinx->sphinx-rtd-theme) (2.10)
Requirement already satisfied: chardet<4,>=3.0.2 in /home/dechin/anaconda3/lib/python3.8/site-packages (from requests>=2.5.0->sphinx->sphinx-rtd-theme) (3.0.4)
Requirement already satisfied: certifi>=2017.4.17 in /home/dechin/anaconda3/lib/python3.8/site-packages (from requests>=2.5.0->sphinx->sphinx-rtd-theme) (2020.6.20)
Requirement already satisfied: urllib3!=1.25.0,!=1.25.1,<1.26,>=1.21.1 in /home/dechin/anaconda3/lib/python3.8/site-packages (from requests>=2.5.0->sphinx->sphinx-rtd-theme) (1.25.11)
Requirement already satisfied: pyparsing>=2.0.2 in /home/dechin/anaconda3/lib/python3.8/site-packages (from packaging->sphinx->sphinx-rtd-theme) (2.4.7)
Requirement already satisfied: six in /home/dechin/anaconda3/lib/python3.8/site-packages (from packaging->sphinx->sphinx-rtd-theme) (1.15.0)
Requirement already satisfied: pytz>=2015.7 in /home/dechin/anaconda3/lib/python3.8/site-packages (from babel>=1.3->sphinx->sphinx-rtd-theme) (2020.1)
Requirement already satisfied: MarkupSafe>=0.23 in /home/dechin/anaconda3/lib/python3.8/site-packages (from Jinja2>=2.3->sphinx->sphinx-rtd-theme) (1.1.1)
Installing collected packages: sphinx-rtd-theme
Successfully installed sphinx-rtd-theme-0.5.1

基于python的量子線路打印小項目

我們先看一下使用的方法以及效果，再回過頭來分析代碼實現的原理：

if __name__ == '__main__':
    qc = QuantumCircuit(3)
    qc.apply(0, 0)
    qc.apply(1, (1,0))
    qc.apply(1, (2,1))
    qc.apply(1, (2,0))
    qc.apply(2)
    print (qc)

輸出結果如下所示(注意使用等寬字體)：

 |0>     |0>     |0>     
  |       |       | 
  |       |       h 
  |       |       | 
  |       x ----- c 
  |       |       | 
  x ----- c       | 
  |       |       | 
  x ----- | ----- c 
  |       |       | 
  m       m       m

這里我們就可以了解到，這個項目的核心功能就是通過構造一個量子線路的對象，并且對這個對象逐一的施加量子門操作，就可以輸出成對應的量子線路字符串。接下來我們再看看源碼實現：

# qcprinter.py
"""
The module used for print a quantum circuit in string format.
"""

class QuantumCircuit:
    """The class of quantum circuit from input quantum logical gates.
    
    Parameters
        ----------
        qubits : int
            Totcal number of qubits used in this quantum circuit.
    
    Returns
        -------
        str
            The string format of quantum circuit.
            
    How to use?
        -------

        >>> qc = QuantumCircuit(3)
        >>> qc.apply(0, 0)
        >>> qc.apply(1, (1,0))
        >>> qc.apply(1, (2,1))
        >>> qc.apply(1, (2,0))
        >>> qc.apply(2)
        >>> print (qc)
    Example output
        -------
    
        >>>  |0>     |0>     |0>     
        >>>   |       |       | 
        >>>   |       |       h 
        >>>   |       |       | 
        >>>   |       x ----- c 
        >>>   |       |       | 
        >>>   x ----- c       | 
        >>>   |       |       | 
        >>>   x ----- | ----- c 
        >>>   |       |       | 
        >>>   m       m       m 
    """
    def __init__(self, qubits=0):
        self.qubits = qubits
        self.str_circuit = ' |0>\t' * self.qubits + ' \n'
    
    def __str__(self):
        return self.str_circuit
    
    def apply(self, gate_type, qubit_index=0):
        """The function used to apply quantum logical gates on quantum state.
        
        Parameters
            ----------
            gate_type : int
                An index number represents for different type of quantum logical gates. 0 for h gate, 
                1 for cx gate and 2 for measure gate.
            qubit_index: int, tuple, none
                The qubit index quantum logical gates allpied on. If the gate_type is h, the qubit_index
                would be int format. If the gate_type is cx, the qubit_index should be a tuple. If the 
                gate_type is m, that means do measurement to all qubits, thus you do not need to set
                the value of qubit_index.
    
        Returns
            -------
            str
                The string format of quantum circuit.
        """
        if gate_type == 0:
            self.str_circuit += '  | \t' * self.qubits + '\n'
            self.str_circuit += '  | \t' * (self.qubits - qubit_index - 1) + '  h \t' + '  | \t' * (qubit_index) + '\n'
        elif gate_type == 1:
            self.str_circuit += '  | \t' * self.qubits + '\n'
            self.str_circuit += '  | \t' * (self.qubits - qubit_index[0] - 1) + '  x'
            for i in range(qubit_index[0] - qubit_index[1] - 1):
                self.str_circuit += ' ' + '-' * 5 + ' |'
            self.str_circuit +=  ' ' + '-' * 5 + ' c \t'
            self.str_circuit += '  | \t' * (qubit_index[1]) + '\n'
        elif gate_type == 2:
            self.str_circuit += '  | \t' * self.qubits + '\n'
            self.str_circuit += '  m \t' * self.qubits + '\n'
        else:
            pass

在這個簡單的代碼實現中，我們主要是為量子線路的類設置了一個魔法函數__str__，將我們所需要的量子線路的字符串作為整個對象的字符串返回值(關于python的魔法函數的使用方法可以參考前面這篇博客介紹)。這個字符串的類的核心功能是通過字符串拼接來實現的，我們不過多的贅述。這里為了方便操作，我們將量子邏輯門操作使用整型數字來替代：0代表HH門，1代表CNOTCNOT門，2代表全局的量子測量操作。同時，為了展示API文檔的制作過程，這里我們在類與函數內都寫了一部分的示例注釋代碼，在下一個章節介紹一下文檔的效果。

sphinx文檔生成與效果一覽

首先使用sphinx-quickstart來生成一些配置文件：

[dechin@dechin-manjaro circuit]$ sphinx-quickstart
歡迎使用 Sphinx 3.5.1 快速配置工具。

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> 獨立的源文件和構建目錄（y/n） [n]: y

The project name will occur in several places in the built documentation.
> 項目名稱: qcprinter
> 作者名稱: DechinPhy
> 項目發行版本 []: 1.0

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> 項目語種 [en]: en

創建文件 /home/dechin/projects/2021-quantum/circuit/source/conf.py。
創建文件 /home/dechin/projects/2021-quantum/circuit/source/index.rst。
創建文件 /home/dechin/projects/2021-quantum/circuit/Makefile。
創建文件 /home/dechin/projects/2021-quantum/circuit/make.bat。

完成：已創建初始目錄結構。

You should now populate your master file /home/dechin/projects/2021-quantum/circuit/source/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

在這一系列的配置之后，會在當前目錄下生成幾個新的文件(由于我們選擇了build和source分離的模式，因此這里會有2個目錄)：

[dechin@dechin-manjaro circuit]$ ll
總用量 52
drwxr-xr-x 2 dechin dechin  4096  2月 23 00:04 build
-rw-r--r-- 1 dechin dechin   799  2月 23 00:04 make.bat
-rw-r--r-- 1 dechin dechin   638  2月 23 00:04 Makefile
-rw-r--r-- 1 dechin dechin  3055  2月 22 23:26 qcprinter.py
drwxr-xr-x 4 dechin dechin  4096  2月 23 00:04 source

在source目錄下會產生一些配置文件，這里我們需要修改其中的conf.py文件：

[dechin@dechin-manjaro circuit]$ cd source/
[dechin@dechin-manjaro source]$ ll
總用量 16
-rw-r--r-- 1 dechin dechin 1884  2月 23 00:04 conf.py
-rw-r--r-- 1 dechin dechin  443  2月 23 00:04 index.rst
drwxr-xr-x 2 dechin dechin 4096  2月 23 00:04 _static
drwxr-xr-x 2 dechin dechin 4096  2月 23 00:04 _templates

可以參考樓主的配置方案，這里我們主要是將主題配置成了rtd的格式，同時打開了autodoc的選項以及通過sys配置了索引目錄(索引目錄不配置的話，有可能導致找不到模塊，從而無法正常的生成API接口文檔)：

[dechin@dechin-manjaro circuit]$ cat source/conf.py 
# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('..'))


# -- Project information -----------------------------------------------------

project = 'qcprinter'
copyright = '2021, DechinPhy'
author = 'DechinPhy'

# The full version, including alpha/beta/rc tags
release = '1.0'


# -- General configuration ---------------------------------------------------
import sphinx_rtd_theme
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["sphinx_rtd_theme", "sphinx.ext.autodoc", "sphinx.ext.autosummary"
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = []


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

執行sphinx-build指令將source中的rst文檔編譯成html文檔，并輸出到build目錄下：

[dechin@dechin-manjaro circuit]$ sphinx-build source/ build/
正在運行 Sphinx v3.5.1
加載 pickled環境... 完成
構建 [mo]： 0 個 po 文件的目標文件已過期
構建 [html]： 0 個源文件的目標文件已過期
更新環境: 已添加 0，1 已更改，0 已移除
閱讀源... [100%] qcprinter                                                                                                                                                                                                                     
/home/dechin/projects/2021-quantum/circuit/qcprinter.py:docstring of qcprinter.QuantumCircuit:4: WARNING: Unexpected section title or transition.

----------
/home/dechin/projects/2021-quantum/circuit/qcprinter.py:docstring of qcprinter.QuantumCircuit:9: WARNING: Unexpected section title or transition.

-------
/home/dechin/projects/2021-quantum/circuit/qcprinter.py:docstring of qcprinter.QuantumCircuit:14: WARNING: Unexpected section title or transition.

-------
/home/dechin/projects/2021-quantum/circuit/qcprinter.py:docstring of qcprinter.QuantumCircuit:24: WARNING: Unexpected section title or transition.

-------
/home/dechin/projects/2021-quantum/circuit/qcprinter.py:docstring of qcprinter.QuantumCircuit.apply:4: WARNING: Unexpected section title or transition.

----------
/home/dechin/projects/2021-quantum/circuit/qcprinter.py:docstring of qcprinter.QuantumCircuit.apply:15: WARNING: Unexpected section title or transition.

-------
查找當前已過期的文件... 沒有找到
pickling環境... 完成
檢查一致性... /home/dechin/projects/2021-quantum/circuit/source/modules.rst: WARNING: 文檔沒有加入到任何目錄樹中
完成
準備文件... 完成
寫入輸出... [ 33%] index                                                                                                                                                                                                                    寫入輸出... [ 66%] modules                                                                                                                                                                                                                  寫入輸出... [100%] qcprinter                                                                                                                                                                                                                    
generating indices... genindex py-modindex 完成
writing additional pages... search 完成
copying static files... 完成
copying extra files... 完成
dumping search index in English (code: en)... 完成
dumping object inventory... 完成
build 成功, 7 warnings.

HTML 頁面保存在 build 目錄。

在這個執行的過程中，有一部分的告警是跟注釋規范相關的，其實不用處理也沒有關系。接下來就可以打開build目錄，查看已經生成成功的html文檔，首先我們可以打開index.html，是常用的網頁主頁索引，大概內容如下圖所示：

我們先點擊這里的index和module看看內容，分別為下列的兩個圖所示：

最后在這個索引列表中我們點擊進入qcprinter這個類中，去查看詳細的類的文檔說明：

相應的函數注釋內容也會在接口文檔中體現：

需要注意的是，如果相關的類或者函數是受保護的類型，那么在sphinx生成的文檔中是不會顯示的(構造過程中自動忽略)。

補充說明（2021.03.27）

如果在使用sphinx的過程中，發現代碼中的注釋文件并未被成功生成。如果成功執行的話，諸如module1.rst和module2.rst等會被自動的生成在source目錄下。這些rst文件沒有被自動生成的情況下，可能需要使用sphinx-apidoc去手動地添加：

[dechin@dechin-manjaro hiqfermion]$ sphinx-apidoc -f src/hiqfermion -o docs/source/
創建文件 docs/source/hiqfermion.rst。
創建文件 docs/source/hiqfermion.ansatzes.rst。
創建文件 docs/source/hiqfermion.drivers.rst。
創建文件 docs/source/hiqfermion.ops.rst。
創建文件 docs/source/hiqfermion.optimizers.rst。
創建文件 docs/source/hiqfermion.third_party.rst。
創建文件 docs/source/hiqfermion.transforms.rst。
創建文件 docs/source/hiqfermion.utils.rst。
創建文件 docs/source/modules.rst。

在上述示例中，src/hiqfermion是源代碼的存放地址，而docs/source是生成的rst文件存放的位置。一般我們需要先生成這些rst文件，再使用sphinx-build執行文檔構建。

還有一點需要注意的是，如果我們直接使用sphinx-apidoc -f src/hiqfermion -o docs/source/這樣的指令去生成的話，最終文檔中的結構都是hiqfermion.module1和hiqfermion.module2，這樣顯得不太簡潔，因為正常情況下我們需要的是module1和module2這樣比較直接的形式。此時我們可以更改其中的module.rst文件。當然，首先我們需要逐一的去執行sphinx-apidoc來生成一些模塊化的rst文件：sphinx-apidoc -f src/hiqfermion/module1 -o docs/source/以及sphinx-apidoc -f src/hiqfermion/module2 -o docs/source/分開執行。這樣我們可以把module.rst修改成這樣的形式：

module1
=======

.. toctree::
   :maxdepth: 4

   module1

module2
=======

.. toctree::
   :maxdepth: 4

   module2

這里rst文檔會自動搜尋同目錄下的module1.rst和module2.rst文件，并自動化的生成文檔。

總結概要

在這篇文章中，我們主要通過一個量子線路打印的python項目介紹，也順帶通過sphinx將python項目的注釋文檔自動化的生成API接口文檔，完成了一個項目開發及文檔輸出流程的簡要分析，在實戰中掌握更多的工具使用方法。

版權聲明

本文首發鏈接為：https://www.cnblogs.com/dechinphy/p/qcprinter.html
作者ID：DechinPhy
更多原著文章請參考：https://www.cnblogs.com/dechinphy/

agxedo是什么？

tagxedo creator中文版是一款詞云圖生成器，采用了Sliverlight，在渲染速度上非常快，具有強大的導入功能，可完美地將詞頻、主題、標簽很好的結合在了一起，幫助用戶輕松創建出美觀的詞云圖。值得一提的是，該軟件在詞云圖表達和突出重點的方式上別具一格，可通過地圖、人物來突出一些重點、關鍵詞。另外，該軟件支持中文，支持多種形狀模板，支持多種顏色主題，可自定義云的外形。

Tagxedo與其他文字云軟件相比優勢在哪？

圖悅（picdata.cn/）：簡單粗暴，復制文本，直接生成文字云。有標準模式、微信模式、地圖模式三中形狀
BPD個人版（me.bpd.cn/home.html）：該軟件主打的是數據分析展示，利用儀表盤進行展示，所以文字云只是小插件，并沒有突出特色。
Tagul（tagul.com/）：和Tagxedo很像的一款，小編個人覺得沒有Tagxedo的界面好看，作出圖片的效果也有一點差距。
WordCloud：Python的一個第三方庫，可在處理數據時，直接將文本轉化為文字云，可以自己選擇圖片，進行形狀展示。需要有一定的Python基礎，但可以作出最滿意的效果。
……還有很多其他的軟件，只列舉了這么多。今天選擇小編最喜歡的一個進行講解——tagxedo

Tagxedo高效使用前的準備

Google Chrome/360瀏覽器
翻墻軟件Psiphon3（可以提高頁面加載速度）
Tagxedo網址tagxedo.com/app.html

Tagxedo操作流程

1.導入文本

打開初始界面

導入文本，有三種方式。一是文件導入，這里要注意的是，文件導入要注意編碼問題，不然顯示出來就是亂碼。二是網址導入，這樣分析的數據有限，僅是一個網頁的數據，且可能會有一些無關數據。三是文本導入，將分析好的數據復制進框中，這是最好的一種導入方式。

三種導入方式

文本導入

初始圖片

導入后，未調整圖片如上，真的是一眼難盡啊，形狀不好看，詞也被分開了。

2.詞語設置（Tagxedo最容易入的坑）

在World丨Layout Options中選擇Word模塊，在Apply NonLatin Heuristics選項下，切換為No。

設置步驟

其他，在這個模塊，還可以設置不同詞的大小、詞語的跳過等等。小編覺得自身生成的設置就挺好了，一般不會再去修改了，如果各位有需要的話，可以在評論區留言或者私信小編喲~

詞語分詞設置后演示圖

3.形狀設置

形狀設置，在Shape模塊下，可在官方提供的模塊中選擇，也可自定義導入圖片。這里演示自定義導入圖片，為中國地圖。

形狀設置步驟

輪廓設置圖

如下圖，調節Threshold和Blur，可以細化形狀的輪廓，讓文字云更好展現。

形狀設置成圖

4.主題設置

在Theme模塊下，可以選擇不同的主題顏色，小編最喜歡Quiet Morning這個主題。此外，其還具有自己添加主題的選項，若有藝術細胞、審美細胞好的小伙伴，可以自己去設置喲。

主題設置圖

5.字體設置

眾多選項，總有你喜歡的那一款

字體設置圖

6.詞語擺放設置

有水平、垂直、水平或垂直、隨意四種選項，小編覺得隨意更自然。

擺放設置圖

7.導出

還有顏色等設置，大家可以自己嘗試一下，是比較容易上手的，小編就不贅述了。最后就是導出圖片了，我一般會選擇PNG格式16MP的圖片。

導出步驟

鐺鐺鐺鐺，最后我們的最終圖片就出來啦~

如果大家還想和小編討論關于Tagxedo的相關問題可以評論區留言或者私信小編喲~

在線咨詢

上一篇：kpnav跨屏網址導航主題模板發布上線
下一篇：前端入門-html 中如何使用圖片

您的項目需求

*請認真填寫需求信息，我們會在24小時內與您取得聯系。

整合營銷服務商