Package: docserve
DocServeA tool for quick and easy Markdown project documentation.DocServe renders an adapted Markdown to provide:Images, Video, YouTube links, CSV tables.Code highlighting.File download blocks.Lists and Tables.Document defined template selection.Document Meta-data.Auto-generated index sidebar.DocServe can be used as a server to:Output documents as insecure HTML on a localhost.Output documents as PDF files via the HTML server.DocServe can also:Create astaticset of HTML files that contain the documentation and related resources.Basic usage with the default template:python-mpipinstalldocserve
mkdirdocs
vimdocs/home.md# then add some documentationdocserveBasic usage with a custom template:python-mpipinstalldocserve
docserve--new# copies sample style and docs into working directorydocserve# run the serverRoadmapWe are requesting pull-requests for the following features:Clearer heading CSS. H1 and H2 are confusing.Test cases and CI stepsReload on new files.Windows EXE bundle for non-developer use.Responsive design in default template.Generate a large PDF file made from multiple documents (including table of contents with page numbers).Gravatar print CSS / absent internet in the default theme.Examples of Python extensions and SCSS extensions.New template themes.Getting StartedIf you are running from the script:pythondocserve.py# start a server on localhost:5000pythondocserve.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 filepythondocserve.py--port# specify a port for docserve to accept requests onpythondocserve.py--pdf# generate a set of pdf files for each .md file - won't pull through# static resource files like with the --html commandpythondocserve.py--new# copy default templates and sample docs into the working directory# and update the config too, only if they don't already existpythondocserve.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.pythondocserve.py--dirs# display all the different directories docserve will use to generate# the documentationpythondocserve.py--find-orphans# display unreferenced media assets in the documentationpythondocserve.py--find-broken-links# display external broken links in the documentationWriting DocumentationDocuments are managed usingmeta-dataat the top of each document.
Documents can select whichtemplatethey present themselves with.
Documents must end inlowercase.md. For example:mydocument.md.Environment variablesDS_FLASK_DEBUGflag for enabling or disabling flask debug. Defaults toTRUE.DS_FLASK_CHANGERELOADflag for reloading the server when a file changes. Defaults toTRUE. If set, this forcesDS_FLASK_DEBUGtoTRUE.DS_WKHTMLTOPDFthe path to the WkHTMLtoPDF binary. Defaults towkhtmltopdf_0.12.5.exe.DS_DOCS_DIRthe path to the directory that contains the documents. Defaults todocs.DS_STYLE_DIRthe path to the directory that contains the style templates and resources. Defaults tostyle.DS_PROJECT_LOGOthe path to the project logoPNGfile. Defaults tologo.pngin the current working directory.DevelopmentVirtual Environmentpython-mvirtualenvenvenv/Scripts/activate.bat# or the bash equivalentpipinstall-rrequirements.txtpythondocserve.py# with optionspipinstallflake8flake8docserve.py--max-line-length=120WkHTMLtoPDFTo enable PDF output, WkHTMLtoPDF must be set in the configDS_WKHTMLTOPDForwkhtmltopdf_0.12.5.exeplaced in working directory.This build uses version 0.12.5. Get it from here:https://wkhtmltopdf.org/downloads.htmlSCSSThe default theme is built using SCSS.The SASSC compiler can be found here:http://libsass.ocbnet.ch/installer/Usage:sassc style/static/default.scss style/static/default.cssIf you want it to auto-watch, run as admin from this directory, and remember to disable your browser cache:pipinstallwatchdog
watchmedoshell-command--patterns="*.scss"--recursive--command='echo "${watch_src_path}" && sassc style/static/default.scss style/static/default.css'.StyleWe useflake8 docserve.py --max-line-length=110to static check the code.Rebuilding the Packagepython -m pip install --user --upgrade setuptools wheel twine
python setup.py sdist bdist_wheel

python -m twine upload dist/*