10be4c06bd
|
||
|---|---|---|
| .. | ||
| lammpsdoc | ||
| tests | ||
| .gitignore | ||
| .travis.yml | ||
| LICENSE | ||
| README.md | ||
| setup.py | ||
README.md
LAMMPS Documentation Utilities
This repository contains a set of utilities to convert existing LAMMPS documentation text files into ReStructured Text. These files can then be used to generate documentation using Sphinx (www.sphinx-doc.org).
The goal of these tools is to simplify the transition to this new format by automatically transforming existing formatting and adding some semantic replacements.
Contents
- A Python port of txt2html
- A new txt2rst utility which transforms txt files directly into ReStructured Text for Sphinx
- Unit tests
Prerequisites
- Currently these tools only run on Python 3
Sphinx requirements
The generated ReStructured Text assumes you've installed both sphinx and
sphinxcontrib-images. Both can be installed through pip:
pip3 install sphinx
pip3 install sphinxcontrib-images
Once Sphinx is set up adjust your configuration conf.py to use the
sphinxcontrib-images extension:
extensions = [
...
'sphinxcontrib.images',
...
]
Installation
-
Clone this repository
-
Install using setup.py
python setup.py install
Usage
Convert .txt files using txt2rst:
# single files
txt2rst Manual.txt > Manual.rst
# multiple files
txt2rst *.txt
Backwards compatibility with txt2html
RST portions
Since the original txt2html passes through HTML tags the following syntax can be used to invalidate RST code:
<!-- RST
.. toctree::
:maxdepth: 2
:numbered:
Section_intro
Section_start
Section_commands
END_RST -->
HTML_ONLY portions
At the same time, some contents of the original txt files might no longer be needed when compiling the RST files using Sphinx. These regions can be marked using a HTML_ONLY region:
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
...
</HEAD>
<BODY>
<!-- END_HTML_ONLY -->