diff --git a/docs/Makefile b/docs/Makefile index 6ba2fa54..2b4de2d8 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -19,6 +19,9 @@ apidoc: server: cd build/html && python -m http.server +dev: + rm -rf build/html && make html && make server + .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..233705ae --- /dev/null +++ b/docs/README.md @@ -0,0 +1,26 @@ +# 快速入门 fastNLP 文档编写 + +本教程为 fastNLP 文档编写者创建，文档编写者包括合作开发人员和文档维护人员。您在一般情况下属于前者， +只需要了解整个框架的部分内容即可。 + +## 合作开发人员 + +FastNLP的文档使用基于[reStructuredText标记语言](http://docutils.sourceforge.net/rst.html)的 +[Sphinx](http://sphinx.pocoo.org/)工具生成，由[Read the Docs](https://readthedocs.org/)网站自动维护生成。 +一般开发者只要编写符合reStructuredText语法规范的文档并通过[PR](https://help.github.com/en/articles/about-pull-requests)， +就可以为fastNLP的文档贡献一份力量。 + +如果你想在本地编译文档并进行大段文档的编写，您需要安装Sphinx工具以及sphinx-rtd-theme主题。然后在本目录下执行`make dev` 命令， +并在浏览器访问 http://0.0.0.0:8000/ 查看文档。 该命令只支持Linux和MacOS系统，在结束查看后需按 Control(Ctrl) + C 退出。 +如果你在远程服务器尚进行工作，您可以通过浏览器访问 http://{服务器的ip地址}:8000/ 查看文档，但必须保证服务器的8000端口是开放的。 +如果您的电脑或远程服务器的8000端口被占用，程序会顺延使用8001、8002……等端口，具体以命令行输出的信息为准。 + +我们在[这里](./source/user/example.rst)列举了fastNLP文档经常用到的reStructuredText语法（网页查看请结合Raw模式）， +您可以通过阅读它进行快速上手。FastNLP大部分的文档都是写在代码中通过Sphinx工具进行抽取生成的， +您还可以参考这篇[未完成的文章](./source/user/docs_in_code.rst)了解代码内文档编写的规范。 + +## 文档维护人员 + +文档维护人员需要了解 Makefile 中全部命令的含义，并了解到目前的文档结构 +是在 sphinx-apidoc 自动抽取的基础上进行手动修改得到的。 +文档维护人员应进一步提升整个框架的自动化程度，并监督合作开发人员不要破坏文档项目的整体结构。 \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 1c651b1f..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build -set SPHINXPROJ=fastNLP - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/quick_tutorial.md b/docs/quick_tutorial.md deleted file mode 100644 index 64c51124..00000000 --- a/docs/quick_tutorial.md +++ /dev/null @@ -1,2 +0,0 @@ -# FastNLP Quick Tutorial - diff --git a/docs/source/user/docs_in_code.rst b/docs/source/user/docs_in_code.rst new file mode 100644 index 00000000..a0b9576f --- /dev/null +++ b/docs/source/user/docs_in_code.rst @@ -0,0 +1,3 @@ +=============== +在代码中写文档 +=============== \ No newline at end of file diff --git a/docs/source/user/example.rst b/docs/source/user/example.rst index d08068c9..5245aaa2 100644 --- a/docs/source/user/example.rst +++ b/docs/source/user/example.rst @@ -20,7 +20,13 @@ 小标题4 ------------------- -参考 http://docutils.sourceforge.net/docs/user/rst/quickref.html +推荐使用大标题、小标题3和小标题4 + +官方文档 http://docutils.sourceforge.net/docs/user/rst/quickref.html + +`熟悉markdown的同学推荐参考这篇文章 `_ + +\<\>内表示的是链接地址，\<\>外的是显示到外面的文字 常见语法 ============ @@ -84,12 +90,14 @@ http://docutils.sf.net/ 孤立的网址会自动生成链接 print("有行号和高亮") 数学块 +========== .. math:: H_2O + Na = NaOH + H_2 \uparrow 复杂表格 +========== +------------------------+------------+----------+----------+ | Header row, column 1 | Header 2 | Header 3 | Header 4 | @@ -105,6 +113,7 @@ http://docutils.sf.net/ 孤立的网址会自动生成链接 +------------------------+------------+---------------------+ 简易表格 +========== ===== ===== ====== Inputs Output @@ -116,11 +125,11 @@ True True True ===== ===== ====== [重要]各种链接 -=================π +=================== 各种链接帮助我们连接到fastNLP文档的各个位置 -\<\>内表示的是地址，\<\>外的是显示到外面的名字， +\<\>内表示的是链接地址，\<\>外的是显示到外面的文字 :doc:`根据文件名链接 `