This tool is no longer necessary. All of the LAMMPS documentation has been successfully converted to ReStructured Text. This repository will now be archived for historic purposes.
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.
- A Python port of txt2html
- A new txt2rst utility which transforms txt files directly into ReStructured Text for Sphinx
- Unit tests
- Currently these tools only run on Python 3
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',
...
]-
Clone this repository
-
Install using setup.py
python setup.py install
Convert .txt files using txt2rst:
# single files
txt2rst Manual.txt > Manual.rst
# multiple files
txt2rst *.txtSince 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 -->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 -->