国产xxxx99真实实拍_久久不雅视频_高清韩国a级特黄毛片_嗯老师别我我受不了了小说

資訊專(zhuān)欄INFORMATION COLUMN

使用 Sphinx 撰寫(xiě)技術(shù)文檔并生成 PDF 總結(jié)

sutaking / 2869人閱讀

摘要:項(xiàng)目代碼認(rèn)識(shí)是一個(gè)基于的文檔生成項(xiàng)目。文檔項(xiàng)目起始文件。將之前的文檔用管理,并推送到,然后在中即可。完成后使用更新。設(shè)置文檔你的第一本書(shū)作者最后,編譯會(huì)完成轉(zhuǎn)換為并將生成,可以手動(dòng)分開(kāi)在下可以查看到生成的文檔。

這幾天準(zhǔn)備編排部分翻譯的書(shū)籍和文檔,找了好些工具,最終定格在 Sphinx 上,并基于 ReadTheDocs 提供的 SaaS 服務(wù)進(jìn)行分發(fā)和分享。本篇博客是對(duì)整個(gè)過(guò)程的一次記錄和總結(jié)。

項(xiàng)目代碼:qiwihui/sphinx-doc-starter

認(rèn)識(shí) Sphinx

Sphinx 是一個(gè)基于 Python 的文檔生成項(xiàng)目。最早只是用來(lái)生成 Python 的項(xiàng)目文檔,使用 reStructuredText 格式。但隨著項(xiàng)目的逐漸完善,很多非 Python 的項(xiàng)目也采用 Sphinx 作為文檔寫(xiě)作工具,甚至完全可以用 Sphinx 來(lái)寫(xiě)書(shū)。

使用 Sphinx 生成文檔的優(yōu)點(diǎn)包括:

豐富的輸出格式: 支持輸出為 HTML(包括 Windows 幫助文檔),LaTeX(可以打印PDF版本), manual pages(man 文檔), 純文本等若干種格式;

完備的交叉引用: 語(yǔ)義化的標(biāo)簽,并可以自動(dòng)化鏈接函數(shù)、類(lèi)、引文、術(shù)語(yǔ)等;

明晰的分層結(jié)構(gòu): 輕松定義文檔樹(shù),并自動(dòng)化鏈接同級(jí)/父級(jí)/下級(jí)文章;

美觀(guān)的自動(dòng)索引: 可自動(dòng)生成美觀(guān)的模塊索引;

精確的語(yǔ)法高亮: 基于 Pygments 自動(dòng)生成語(yǔ)法高亮;

開(kāi)放的擴(kuò)展: 支持代碼塊的自動(dòng)測(cè)試,自動(dòng)包含 Python 的模塊自述文檔,等等。

開(kāi)始

這個(gè)過(guò)程包括如下步驟:

安裝 Sphinx

第一個(gè)文檔

在線(xiàn)托管

生成 PDF

安裝 Sphinx

Sphinx 依賴(lài)于 Python,并提供了 Python 包,所以使用 pip 安裝既可。這里我只安裝了 sphinx-doc 這個(gè)包。

</>復(fù)制代碼

  1. pip install sphinx-doc

這時(shí),通過(guò) bash 自動(dòng)補(bǔ)全(連續(xù)兩下 tab),可以看到有幾個(gè)命令,Sphinx 推薦使用 sphinx-quickstart,這是一個(gè)設(shè)置向?qū)А?/p>

</>復(fù)制代碼

  1. $ sphinx-
  2. sphinx-apidoc sphinx-autogen sphinx-build sphinx-quickstart
設(shè)置 Sphinx

運(yùn)行 sphinx-quickstart,以下主要設(shè)置項(xiàng)目名稱(chēng),作者名稱(chēng)以及語(yǔ)言(zh_CN)即可,其他默認(rèn)。

</>復(fù)制代碼

  1. $ sphinx-quickstart
  2. Welcome to the Sphinx 1.8.4 quickstart utility.
  3. Please enter values for the following settings (just press Enter to
  4. accept a default value, if one is given in brackets).
  5. Selected root path: .
  6. You have two options for placing the build directory for Sphinx output.
  7. Either, you use a directory "_build" within the root path, or you separate
  8. "source" and "build" directories within the root path.
  9. > Separate source and build directories (y/n) [n]: y
  10. Inside the root directory, two more directories will be created; "_templates"
  11. for custom HTML templates and "_static" for custom stylesheets and other static
  12. files. You can enter another prefix (such as ".") to replace the underscore.
  13. > Name prefix for templates and static dir [_]:
  14. The project name will occur in several places in the built documentation.
  15. > Project name: 一本書(shū)
  16. > Author name(s): qiwihui
  17. > Project release []: 0.0.1
  18. If the documents are to be written in a language other than English,
  19. you can select a language here by its language code. Sphinx will then
  20. translate text that it generates into that language.
  21. For a list of supported codes, see
  22. http://sphinx-doc.org/config.html#confval-language.
  23. > Project language [en]: zh_CN
  24. The file name suffix for source files. Commonly, this is either ".txt"
  25. or ".rst". Only files with this suffix are considered documents.
  26. > Source file suffix [.rst]:
  27. One document is special in that it is considered the top node of the
  28. "contents tree", that is, it is the root of the hierarchical structure
  29. of the documents. Normally, this is "index", but if your "index"
  30. document is a custom template, you can also set this to another filename.
  31. > Name of your master document (without suffix) [index]:
  32. Indicate which of the following Sphinx extensions should be enabled:
  33. > autodoc: automatically insert docstrings from modules (y/n) [n]:
  34. > doctest: automatically test code snippets in doctest blocks (y/n) [n]:
  35. > intersphinx: link between Sphinx documentation of different projects (y/n) [n]:
  36. > todo: write "todo" entries that can be shown or hidden on build (y/n) [n]:
  37. > coverage: checks for documentation coverage (y/n) [n]:
  38. > imgmath: include math, rendered as PNG or SVG images (y/n) [n]:
  39. > mathjax: include math, rendered in the browser by MathJax (y/n) [n]:
  40. > ifconfig: conditional inclusion of content based on config values (y/n) [n]:
  41. > viewcode: include links to the source code of documented Python objects (y/n) [n]:
  42. > githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]:
  43. A Makefile and a Windows command file can be generated for you so that you
  44. only have to run e.g. `make html` instead of invoking sphinx-build
  45. directly.
  46. > Create Makefile? (y/n) [y]:
  47. > Create Windows command file? (y/n) [y]:
  48. Creating file ./source/conf.py.
  49. Creating file ./source/index.rst.
  50. Creating file ./Makefile.
  51. Creating file ./make.bat.
  52. Finished: An initial directory structure has been created.
  53. You should now populate your master file ./source/index.rst and create other documentation
  54. source files. Use the Makefile to build the docs, like so:
  55. make builder
  56. where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

解釋1,整個(gè)設(shè)置過(guò)程包括:

是否分離源文件目錄 source 和生成文件目錄 build,默認(rèn)否;

模板目錄 templates 和靜態(tài)文件目錄 static 前綴,默認(rèn)為_

項(xiàng)目名稱(chēng);

項(xiàng)目作者;

項(xiàng)目版本,默認(rèn)為空;

項(xiàng)目語(yǔ)言,默認(rèn)為 en

文檔擴(kuò)展名,默認(rèn)為 .rst

首頁(yè)文件名,默認(rèn)為 index

開(kāi)啟的擴(kuò)展,均默認(rèn)為否:

autodoc

doctest

intersphinx

todo

coverage

imgmath

mathjax

ifconfig

viewcode

githubpages

生成 Makefile,默認(rèn)是;

生成 Windows 用命令行,默認(rèn)是。

解釋2,項(xiàng)目目錄文件結(jié)構(gòu)如下:

</>復(fù)制代碼

  1. sphinx-test
  2. ├── Makefile
  3. ├── build
  4. ├── make.bat
  5. └── source
  6. ├── _static
  7. ├── _templates
  8. ├── conf.py
  9. └── index.rst

其中:

Makefile:可以看作是一個(gè)包含指令的文件,在使用 make 命令時(shí),可以使用這些指令來(lái)構(gòu)建文檔輸出。

build:生成的文件的輸出目錄。

make.bat:Windows 用命令行。

_static:靜態(tài)文件目錄,比如圖片等。

_templates:模板目錄。

conf.py:存放 Sphinx 的配置,包括在 sphinx-quickstart 時(shí)選中的那些值,可以自行定義其他的值。

index.rst:文檔項(xiàng)目起始文件。

接下來(lái)看看默認(rèn)生成的內(nèi)容:

</>復(fù)制代碼

  1. $ make html
  2. Running Sphinx v1.8.4
  3. loading translations [zh_CN]... done
  4. making output directory...
  5. building [mo]: targets for 0 po files that are out of date
  6. building [html]: targets for 1 source files that are out of date
  7. updating environment: 1 added, 0 changed, 0 removed
  8. reading sources... [100%] index looking for now-outdated files... none found
  9. pickling environment... done
  10. checking consistency... done
  11. preparing documents... done
  12. writing output... [100%] index generating indices... genindex
  13. writing additional pages... search
  14. copying static files... done
  15. copying extra files... done
  16. dumping search index in Chinese (code: zh) ... done
  17. dumping object inventory... done
  18. build succeeded.
  19. The HTML pages are in build/html.

然后直接在瀏覽器中打開(kāi) build/html/index.html 這個(gè)文件。

默認(rèn)風(fēng)格為 alabaster,可以改成 ReadTheDocs 的風(fēng)格: sphinx_rtd_theme

</>復(fù)制代碼

  1. # -- Options for HTML output -------------------------------------------------
  2. # The theme to use for HTML and HTML Help pages. See the documentation for
  3. # a list of builtin themes.
  4. #
  5. html_theme = "sphinx_rtd_theme"

第一個(gè)文檔

我們以一下文檔為例:

</>復(fù)制代碼

  1. This is a Title
  2. ===============
  3. That has a paragraph about a main subject and is set when the "="
  4. is at least the same length of the title itself.
  5. Subject Subtitle
  6. ----------------
  7. Subtitles are set with "-" and are required to have the same length
  8. of the subtitle itself, just like titles.
  9. Lists can be unnumbered like:
  10. * Item Foo
  11. * Item Bar
  12. Or automatically numbered:
  13. #. Item 1
  14. #. Item 2
  15. Inline Markup
  16. -------------
  17. Words can have *emphasis in italics* or be **bold** and you can define
  18. code samples with back quotes, like when you talk about a command: ``sudo``
  19. gives you super user powers!

將之寫(xiě)入 example.rst 中,并修改 index.rst 為:

</>復(fù)制代碼

  1. Welcome to 一本書(shū)"s documentation!
  2. ==================================
  3. .. toctree::
  4. :maxdepth: 2
  5. :caption: 目錄:
  6. example
  7. Indices and tables
  8. ==================
  9. * :ref:`genindex`
  10. * :ref:`modindex`
  11. * :ref:`search`

重新編譯,這時(shí)文檔已經(jīng)改變。


在線(xiàn)托管

ReadTheDocs 可是直接用于托管 sphinx 生成的網(wǎng)頁(yè)文檔。
將之前的文檔用 Git 管理,并推送到 Github,然后在 ReadTheDocs 中 Import a Project 即可。

另外,可以設(shè)置自定義域名:

在域名管理中添加 DNS 的 CNAME 記錄到 readthedocs.io,比如 onebook.qiwihui.com

在項(xiàng)目的 Admin -> Domains 中設(shè)置上一步添加的域名,開(kāi)啟 HTTPS,保存即可。

過(guò)程很簡(jiǎn)單。

生成 PDF

Sphinx 生成 PDF 的過(guò)程先將 rst 轉(zhuǎn)換為 tex,再生產(chǎn)PDF。這個(gè)過(guò)程遇到了比較多的坑,最后總結(jié)下來(lái)過(guò)程如下:

首先,安裝 Tex 環(huán)境。在 Mac 上,推薦安裝 MacTex 而不是 BasicTex,對(duì)于新手來(lái)說(shuō) BasicTex 上需要自己處理很多以來(lái)問(wèn)題。完成后使用 tlmgr 更新 TexLive。

</>復(fù)制代碼

  1. $ brew cask install mactex
  2. $ sudo tlmgr update --self

然后,在 con.py 中設(shè)置 latex_enginelatex_elements 兩個(gè)參數(shù),同時(shí)也可以設(shè)置 latex_documents 參數(shù)來(lái)設(shè)置文檔。

</>復(fù)制代碼

  1. latex_engine = "xelatex"
  2. latex_elements = {
  3. "papersize": "a4paper",
  4. "pointsize": "11pt",
  5. "preamble": r"""
  6. usepackage{xeCJK}
  7. setCJKmainfont[BoldFont=STZhongsong, ItalicFont=STKaiti]{STSong}
  8. setCJKsansfont[BoldFont=STHeiti]{STXihei}
  9. setCJKmonofont{STFangsong}
  10. XeTeXlinebreaklocale "zh"
  11. XeTeXlinebreakskip = 0pt plus 1pt
  12. parindent 2em
  13. definecolor{VerbatimColor}{rgb}{0.95,0.95,0.95}
  14. setcounter{tocdepth}{3}
  15. enewcommandfamilydefault{
  16. tdefault}
  17. enewcommandCJKfamilydefault{CJKrmdefault}
  18. """
  19. }
  20. # 設(shè)置文檔
  21. latex_documents = [
  22. (master_doc, "sphinx.tex", "你的第一本 Sphinx 書(shū)",
  23. "作者:qiwihui", "manual", True),
  24. ]

最后,編譯:

</>復(fù)制代碼

  1. $ make latexpdf

make latexpdf 會(huì)完成 rst轉(zhuǎn)換為 tex 并將 tex 生成 PDF,可以手動(dòng)分開(kāi):

</>復(fù)制代碼

  1. $ make latex
  2. $ cd build/latex
  3. $ make

build/latex 下可以查看到生成的 PDF 文檔。

字體

使用 fc-list 來(lái)獲取字體信息,修改相應(yīng)字體設(shè)置即可。

</>復(fù)制代碼

  1. $ brew install fontconfig
  2. $ fc-list :lang=zh
遇到的問(wèn)題:

遇到 "! LaTeX Error: File "*.sty" not found." 類(lèi)的問(wèn)題:

解決:使用 sudo tlmgr install 安裝相應(yīng)的包即可。

總結(jié)

簡(jiǎn)單過(guò)了一下整個(gè)文檔的流程,總體來(lái)說(shuō),Sphinx非常適合用來(lái)編寫(xiě)項(xiàng)目文檔,reStructuredText 比起 Markdown 也有太多的優(yōu)勢(shì),值得推薦。

</>復(fù)制代碼

  1. GitHub repo: qiwihui/blog

    Follow me: @qiwihui

  2. Site: QIWIHUI

文章版權(quán)歸作者所有,未經(jīng)允許請(qǐng)勿轉(zhuǎn)載,若此文章存在違規(guī)行為,您可以聯(lián)系管理員刪除。

轉(zhuǎn)載請(qǐng)注明本文地址:http://m.specialneedsforspecialkids.com/yun/43251.html

相關(guān)文章

  • sphinx快速入門(mén)

    摘要:簡(jiǎn)介是一個(gè)用于快速生成文檔的工具,非常適合生成文檔。稱(chēng)之為主文檔,它被作為歡迎頁(yè)面。由于是默認(rèn)的域,所以并不需要特別指出所屬的域來(lái)。自動(dòng)生成文檔注釋支持從源代碼中提取文檔注釋信息,然后生成文檔,我們將這稱(chēng)之為。 簡(jiǎn)介 sphinx是一個(gè)用于快速生成文檔的工具,非常適合生成Python文檔。 它具有以下優(yōu)點(diǎn): 支持多種輸出格式, 如html,Latex,ePub等。 豐富的擴(kuò)展 結(jié)構(gòu)化...

    yexiaobai 評(píng)論0 收藏0
  • [原]文檔定義應(yīng)用:數(shù)據(jù)科學(xué)的文檔革命

    摘要:對(duì)于數(shù)據(jù)科學(xué)的研究可以說(shuō)已經(jīng)是本文我將介紹如何以文檔定義應(yīng)用的方式成為數(shù)據(jù)科學(xué)中的標(biāo)準(zhǔn)交付。參考前文解密的數(shù)據(jù)科學(xué)部門(mén)如果構(gòu)建知識(shí)倉(cāng)庫(kù),作為一個(gè)謝大大的死忠,我很自然選擇了作為我文檔輸出的首選工具。 showImg(https://segmentfault.com/img/remote/1460000006760433?w=423&h=426); 概述 隨著近年來(lái),Rstudio 通過(guò)...

    wh469012917 評(píng)論0 收藏0
  • php + MongoDB + Sphinx 實(shí)現(xiàn)全文檢索

    摘要:此文成于年月現(xiàn)狀目前的穩(wěn)定版本為目前對(duì)英文等字母語(yǔ)言采用空格分詞故其對(duì)中文分詞支持不好目前官方中文分詞方案僅支持按單字分詞在基礎(chǔ)上目前國(guó)內(nèi)有兩個(gè)中文分詞解決方案一個(gè)是一個(gè)是沒(méi)有官網(wǎng)文檔較少可查到的最新版本可支持官方還在維護(hù)但貌似不打 NOTE : 此文成于 2017 年 3 月. 現(xiàn)狀: Sphinx 目前的穩(wěn)定版本為 2.2.11.Sphinx 目前對(duì)英文等字母語(yǔ)言采用空格分詞,故...

    Simon_Zhou 評(píng)論0 收藏0

發(fā)表評(píng)論

0條評(píng)論

最新活動(dòng)
閱讀需要支付1元查看
<