|
我們經(jīng)常可以看到這種的doc文檔,簡潔大方.作為閱讀可謂看著是賞心悅目 那么我能不能自己做一個(gè)這樣的doc呢,我想是可以的,大家跟著我試試看! https://robomaster-dev.readthedocs.io/zh_CN/latest/python_sdk/beginner_multi_robot.html最近一位朋友想做個(gè)大疆的EP車,我提供一些建議,在看Dji的SDK,我就順手拿這個(gè)來做示范了. https://iridescent.ink/HowToMakeDocs/Basic/Sphinx.htmlhttps://zh-sphinx-doc.readthedocs.io/en/latest/tutorial.html我們實(shí)現(xiàn)上述的目的,使用的是Sphinx: Sphinx 是一種文檔工具,，它可以令人輕松的撰寫出清晰且優(yōu)美的文檔, 由 Georg Brandl 在BSD 許可證下開發(fā). 新版的Python文檔就是由Sphinx生成的,， 并且它已成為Python項(xiàng)目首選的文檔工具,同時(shí)它對(duì) C/C++ 項(xiàng)目也有很好的支持; 并計(jì)劃對(duì)其它開發(fā)語言添加特殊支持. 本站當(dāng)然也是使用 Sphinx 生成的，它采用reStructuredText! Sphinx還在繼續(xù)開發(fā). 下面列出了其良好特性,這些特性在Python官方文檔中均有體現(xiàn):
Sphinx 使用 reStructuredText 作為標(biāo)記語言, 可以享有 Docutils 為reStructuredText提供的分析,，轉(zhuǎn)換等多種工具. 此為最新的Python文檔 https://docs.python.org/zh-cn/3/首先創(chuàng)建一個(gè)文件夾,為了避免污染環(huán)境 先看看目錄 在pip 是否分離source和build目錄（輸入y,選擇分離,，方便管理) 歡迎使用Sphinx 3.3.0快速入門實(shí)用程序。 請(qǐng)輸入以下設(shè)置的值（只需按Enter 接受默認(rèn)值（如果在括號(hào)中給出）,。 選定的根路徑：,。 您有兩個(gè)選擇來放置Sphinx輸出的構(gòu)建目錄。 您可以在根路徑中使用目錄“ _build”,，也可以單獨(dú)使用 根路徑中的“源”和“構(gòu)建”目錄。 有一些提示,自己摁 項(xiàng)目名稱將在生成的文檔中的多個(gè)位置出現(xiàn),。>項(xiàng)目名稱：yunswj>作者姓名：yunswj>項(xiàng)目發(fā)布[]：0.1如果要用英語以外的其他語言寫文件,，您可以在此處通過語言代碼選擇一種語言。獅身人面像將其生成的文本翻譯成該語言,。有關(guān)受支持代碼的列表,，請(qǐng)參見https://www./zh-CN/master/usage/configuration.html#confval-language。>項(xiàng)目語言[zh]：創(chuàng)建文件C：\ Users \ yunswj \ Desktop \ Sphinx \ source \ conf.py,。創(chuàng)建文件C：\ Users \ yunswj \ Desktop \ Sphinx \ source \ index.rst,。創(chuàng)建文件C：\ Users \ yunswj \ Desktop \ Sphinx \ Makefile,。創(chuàng)建文件C：\ Users \ yunswj \ Desktop \ Sphinx \ make.bat。完成：初始目錄結(jié)構(gòu)已創(chuàng)建,。現(xiàn)在,，您應(yīng)該填充主文件C：\ Users \ yunswj \ Desktop \ Sphinx \ source \ index.rst并創(chuàng)建其他文檔源文件。使用Makefile構(gòu)建文檔,，如下所示： 使建設(shè)者其中“構(gòu)建器”是受支持的構(gòu)建器之一,，例如html，latex或linkcheck,。項(xiàng)目名字 編輯者姓名 文檔的版本號(hào) 項(xiàng)目語言,我這邊選擇默認(rèn)了.回車就好
會(huì)生成這些文件.
這是生成的結(jié)構(gòu)
config.py的詳細(xì)信息https://www./en/master/usage/configuration.html
這個(gè)是配置文件可以看到是和我創(chuàng)建文件的時(shí)候的內(nèi)容相符 https://www./en/master/usage/configuration.html
顯示錯(cuò)誤,很智能的提醒我用.\這種語法
可以輸出的類型,有一些并不可以輸出.缺少東西
.\make 文件類型 運(yùn)行Sphinx v3.3.0制作輸出目錄...完成建立[mo]：過時(shí)的0個(gè)po文件的目標(biāo)建立[html]：過時(shí)的1個(gè)源文件的目標(biāo)更新環(huán)境：[新配置]添加了1個(gè),，更改了0個(gè)，刪除了0個(gè)閱讀來源... [100％]索引尋找過時(shí)的檔案...找不到酸洗環(huán)境...完成檢查一致性...完成正在準(zhǔn)備文件...完成寫輸出... [100％]索引生成索引... genindex完成寫其他頁面...搜索完成復(fù)制靜態(tài)文件...完成復(fù)制多余的文件...完成用英語（代碼：en）傾銷搜索索引...完成傾銷對(duì)象清單...完成建立成功,。HTML頁面位于build \ html中,。
編譯過后的目錄是這樣的
里面有三個(gè)html文件,都打開看看
以上是打開的三個(gè)網(wǎng)頁文檔 那我寫完就想自動(dòng)預(yù)覽文檔,咋辦?當(dāng)然可以啦
這個(gè)是我的瀏覽器的位置,你如果也是chrome,可以直接復(fù)制我的地址 C:\Program Files\Google\Chrome\Application
把瀏覽器的目錄加環(huán)境變量,自己找
在:end和popd中間加代碼 :end REM ---------------------------------------------- REM Added by Yunswj - Auto open build file REM ---------------------------------------------- if "%1" == "html" ( chrome build/html/index.html )popd
改成這樣
第一次報(bào)錯(cuò)
powershell還是不可以
用cmd打開正常,這個(gè)powershell其實(shí)更shell一些
此時(shí),我們要看一眼托管以及用他家的主題 https://readthedocs.org/
我用Github登錄了
就是一個(gè)托管平臺(tái),巴適的很 https://readthedocs.org/projects/yunswj-demo/
這些指令是生成自己的doc
這個(gè)是默認(rèn)生成的doc
這個(gè)是源代碼
云服務(wù)器編譯,有點(diǎn)好用
詳細(xì)設(shè)置
可以導(dǎo)入自己的文檔(在線)
可以看到有很多詳細(xì)的選項(xiàng) https://readthedocs.org/dashboard/import/manual/?可以這樣用地址導(dǎo)入 https://github.com/readthedocs/template
pip install sphinx_rtd_theme這里我也不托管,先搞一手主題
安裝
成功 # for using Read the Docs themeimport sphinx_rtd_theme
# html_theme = 'sphinxdoc'html_theme = 'sphinx_rtd_theme'#html_theme_path = []html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
重新編譯沒有變化
為了可以自動(dòng)預(yù)覽,用cmd
還是主題未變,之后在解決 支持markdown文件、更改文檔主題Spinx本身不支持.md文件生成文檔,，需要我們使用第三方庫recommonmark進(jìn)行轉(zhuǎn)換,。首先分別運(yùn)行下列命令安裝recommonmark與sphinx_rtd_theme庫。 pip install recommonmark安裝好,，在conf.py中修改下列兩個(gè)配置： source_suffix = ['.rst', '.md', '.MD']并新增： source_parsers = {https://sphinx-doc-zh.readthedocs.io/en/latest/tutorial.html這篇已經(jīng)很多了,下篇繼續(xù)寫
|
|
|
