A tool for quick and easy Markdown project documentation.
Project description
DocServe
A 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 a static set of HTML files that contain the documentation and related resources.
Basic usage with the default template:
python -m pip install docserve
mkdir docs
vim docs/home.md # then add some documentation
docserve
Basic usage with a custom template:
python -m pip install docserve
docserve --new # copies sample style and docs into working directory
docserve # run the server
Roadmap
We are requesting pull-requests for the following features:
- PIP package.
- Add support for changing the default Flask host and port.
- 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.
- Python Package (python -m docserve mydocsdir) with default style.
- Examples of Python extensions and SCSS extensions.
- New template themes.
Getting Started
If you are running from the script:
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 --new # copy default templates and sample docs into the working directory
# and update the config to
python docserve.py --dirs # display all the different directories docserve will use to generate
# the documentation
Writing Documentation
Documents are managed using meta-data
at the top of each document.
Documents can select which template
they present themselves with.
Documents must end in lowercase .md
. For example: mydocument.md
.
Environment variables
DS_FLASK_DEBUG
flag for enabling or disabling flask debug. Defaults toTRUE
.DS_FLASK_CHANGERELOAD
flag for reloading the server when a file changes. Defaults toTRUE
.DS_WKHTMLTOPDF
the path to the WkHTMLtoPDF binary. Defaults towkhtmltopdf_0.12.5.exe
.DS_DOCS_DIR
the path to the directory that contains the documents. Defaults todocs
.DS_STYLE_DIR
the path to the directory that contains the style templates and resources. Defaults tostyle
.DS_PROJECT_LOGO
the path to the project logo PNG file. Defaults tologo.png
in the current working directory.
Development
Virtual Environment
python -m virtualenv env
env/Scripts/activate.bat # or the bash equivalent
pip install -r requirements.txt
python docserve.py # with options
pip install flake8
flake8 docserve.py --max-line-length=120
WkHTMLtoPDF
To enable PDF output, WkHTMLtoPDF must be set in the config DS_WKHTMLTOPDF
or wkhtmltopdf_0.12.5.exe
placed in working directory.
This build uses version 0.12.5. Get it from here: https://wkhtmltopdf.org/downloads.html
SCSS
The 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.css
If you want it to auto-watch, run as admin from this directory, and remember to disable your browser cache:
pip install watchdog
watchmedo shell-command --patterns="*.scss" --recursive --command='echo "${watch_src_path}" && sassc style/static/default.scss style/static/default.css' .
Style
We use flake8 docserve.py --max-line-length=110
to static check the code.
Rebuilding the Package
python -m pip install --user --upgrade setuptools wheel twine
python setup.py sdist bdist_wheel
twine upload --repository-url https://test.pypi.org/legacy/ dist/*
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.