ntDocutils

Docutils theme manager.

ntDocutils is a theme manager for Docutils. It acts as a wrapper for the rst2html5.py frontend, and that enables the customization possibility of the resulting file.

Install

Requirements:

Python >= 3.4

From PyPI

$ pip install NtDocutils

From source

$ wget https://github.com/ntrrg/ntdocutils/archive/v1.0.0.tar.gz

$ tar -xvf v1.0.0.tar.gz

$ cd ntdocutils-1.0.0

$ python3 setup.py

Usage

Basically, you have to do two things:

1. Create a .rst file:

example.rst:

==========
My Article
==========

:Author: Vultur Gryphus
:Contact: [email protected]

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
ex ea commodo consequat. Duis aute irure dolor in reprehenderit in
voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur
sint occaecat cupidatat non proident, sunt in culpa qui officia
deserunt mollit anim id est laborum.

2. Process your file:

$ ntdocutils example.rst example.html

And that’s it, you already have a HTML file, just like Docutils.

To use a theme, just install it and pass the -T THEME flag, for example, to use the MDL theme:

$ pip install ntdocutils-theme-mdl

$ ntdocutils -T mdl example.rst example.html

And this is the result:

CLI

$ ntdocutils -h
usage: ntdocutils [-h] [-V] [-T THEME] [-S SERVER] SOURCE DESTINATION

NtDocutils is a theme manager for Docutils.

positional arguments:
  SOURCE                file to process.
  DESTINATION           file to generate.

optional arguments:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  -T THEME, --theme THEME
                        theme used to generate DESTINATION.
  -S SERVER, --server SERVER
                        server from where assets will be downloaded. If
                        'local' is passed as value, it will activate the
                        offline mode, this will create a directory with the
                        theme name in the 'DESTINATION' parent folder and
                        stores the necessary assets in there.

NtDocutils v1.0.0 https://nt.web.ve/en/projects/ntdocutils
Copyright (c) 2017 Miguel Angel Rivera Notararigo
Licensed under The MIT License

Themes

Create a theme

1. Get the template.

$ git clone \
  --depth 1 \
https://github.com/ntrrg/ntdocutils-theme-template.git \
REPOSITORY_NAME

2. Set up the template.

$ cd REPOSITORY_NAME

$ EDITOR config.sh

config.sh:

NAME="test"
VERSION="1.0.0"
DESCRIPTION="This is a test theme."
URL="https://github.com/ntrrg/ntdocutils-theme-test"
AUTHOR="Miguel Angel Rivera Notararigo"
EMAIL="[email protected]"
SERVER="https://ntrrg.github.io/ntdocutils-theme-test/ntdocutils-theme-test"

$ ./setup.sh

3. Edit and test the template (see the MDL theme code and use it as example).

$ pip install -e .

$ cd docs

$ ntdocutils -T THEME_NAME -S local demo.rst index.html

4. Publish the theme.

Note: a Python account is needed (create an account).

$ rm -rf ntdocutils-theme-THEME_NAME

$ cd ..

$ pip install setuptools twine

$ rm -rf dist

$ python setup.py sdist bdist_well

$ twine upload dist/*

Uninstall

$ pip uninstall -y NtDocutils docutils Pygments

Contributing

See the contribution guide for more information.

Acknowledgment

Working on this project I use/used:

Docutils Team. reStructuredText. http://docutils.sourceforge.net/rst.html

Mozilla Developer Network. JavaScript. https://developer.mozilla.org/en-US/docs/Web/JavaScript

Privacy policy