一个快速和容易标记项目文档的工具。
docserve的Python项目详细描述
docserve
一个快速和容易标记项目文档的工具。
DocServe提供一个适当的降价以提供：
- 图片，视频，youtube链接，csv表格。
- 代码突出显示。
- 文件下载块。
- 列表和表格。
- 文档定义的模板选择。
- 文档元数据。
- 自动生成索引侧边栏。
DocServe可用作服务器：
- 在本地主机上将文档输出为不安全的HTML。
- 通过html服务器将文档输出为pdf文件。
Docserve还可以：
- 创建一个static包含文档和相关资源的html文件集。
默认模板的基本用法：
python -m pip install docserve
mkdir docs
vim docs/home.md # then add some documentation
docserve
自定义模板的基本用法：
python -m pip install docserve docserve --new # copies sample style and docs into working directory docserve # run the server
路线图
我们正在请求以下功能的拉取请求：
- []更清晰的标题css。h1和h2混淆了。
- []测试用例和ci步骤
- []重新加载新文件。
- []非开发人员使用的Windows EXE包。
- []默认模板中的响应式设计。
- []生成由多个文档（包括带有页码的目录）组成的大型PDF文件。
- []Gravatar在默认主题中打印CSS/缺少Internet。
- []python扩展和scss扩展的示例。
- []新模板主题。
开始
如果您正在运行脚本：
python docserve.py # start a server on localhost:5000 python docserve.py --html # freeze the server into a static site as a set of HTML files# this will exit with -1 if there was a problem parsing any file python docserve.py --port # specify a port for docserve to accept requests on python docserve.py --pdf # generate a set of pdf files for each .md file - won't pull through# static resource files like with the --html command python docserve.py --new # copy default templates and sample docs into the working directory# and update the config too, only if they don't already exist python docserve.py --new-force # copy default templates and sample docs into the working directory# and update the config too, this will overwrite any existing docs or# configs. python docserve.py --dirs # display all the different directories docserve will use to generate# the documentation python docserve.py --find-orphans # display unreferenced media assets in the documentation python docserve.py --find-broken-links # display external broken links in the documentation
编写文档
文档使用每个文档顶部的meta-data进行管理。
文档可以选择它们呈现给自己的template。
文档必须以小写.md结尾。例如：mydocument.md。
环境变量
DS_FLASK_DEBUG用于启用或禁用烧瓶调试的标志。默认为TRUE。DS_FLASK_CHANGERELOAD文件更改时重新加载服务器的标志。默认为TRUE。如果设置，则强制将DS_FLASK_DEBUG设置为TRUE。DS_WKHTMLTOPDFwkhtmltopf二进制文件的路径。默认为wkhtmltopdf_0.12.5.exe。DS_DOCS_DIR包含文档的目录的路径。默认为docs。DS_STYLE_DIR指向包含样式模板和资源的目录的路径。默认为style。DS_PROJECT_LOGO项目徽标png文件的路径。默认为当前工作目录中的logo.png。
开发
虚拟环境
python-mvirtualenvenvenv/Scripts/activate.bat# or the bash equivalentpipinstall-rrequirements.txt
pythondocserve.py# with options
pipinstallflake8flake8docserve.py--max-line-length=120
wkhtmltopdf
要启用pdf输出，必须在工作目录中的配置DS_WKHTMLTOPDF或wkhtmltopdf_0.12.5.exe中设置wkhtmltopfd。
此版本使用0.12.5版。从这里获取：https://wkhtmltopdf.org/downloads.html
SCSS
默认主题是使用scss构建的。
sassc编译器可以在这里找到：http://libsass.ocbnet.ch/installer/
用法：sassc style/static/default.scss style/static/default.css
如果您想让它自动观看，请在此目录中以管理员身份运行，并记住禁用浏览器缓存：
pip install watchdog watchmedo shell-command --patterns="*.scss" --recursive --command='echo "${watch_src_path}" && sassc style/static/default.scss style/static/default.css' .
风格
我们使用flake8 docserve.py --max-line-length=110来静态检查代码。
重建包
python -m pip install --user --upgrade setuptools wheel twine
python setup.py sdist bdist_wheel
python -m twine upload dist/*
欢迎加入QQ群-->： 979659372
