lammps/doc/utils/converters
Richard Berger 621d7d5ce0 Correct off-by-one error in line number reported 2017-03-16 23:05:03 -04:00
..
lammpsdoc Correct off-by-one error in line number reported 2017-03-16 23:05:03 -04:00
tests Fix issue with external links containing anchors 2016-10-06 20:29:07 -04:00
.gitignore consolidate ignoring python bytecompiled cache files 2016-09-17 09:50:49 -04:00
.travis.yml git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14950 f3b2605a-c512-4ea7-a41b-209d697bcdaa 2016-05-09 17:22:38 +00:00
LICENSE git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14950 f3b2605a-c512-4ea7-a41b-209d697bcdaa 2016-05-09 17:22:38 +00:00
README.md git-svn-id: svn://svn.icms.temple.edu/lammps-ro/trunk@14950 f3b2605a-c512-4ea7-a41b-209d697bcdaa 2016-05-09 17:22:38 +00:00
setup.py Add utility to detect duplicate anchors in documentation files 2017-03-16 22:21:12 -04:00

README.md

LAMMPS Documentation Utilities

Build Status

Coverage Status

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

  1. Clone this repository

  2. 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 -->