Page Menu
Home
c4science
Search
Configure Global Search
Log In
Files
F87034472
README.md
No One
Temporary
Actions
Download File
Edit File
Delete File
View Transforms
Subscribe
Mute Notifications
Award Token
Subscribers
None
File Metadata
Details
File Info
Storage
Attached
Created
Thu, Oct 10, 03:38
Size
2 KB
Mime Type
text/html
Expires
Sat, Oct 12, 03:38 (1 d, 23 h)
Engine
blob
Format
Raw Data
Handle
21466937
Attached To
rLAMMPS lammps
README.md
View Options
# LAMMPS Documentation Utilities
[![Build Status](https://travis-ci.org/rbberger/lammps-doc-utils.svg?branch=master)](https://travis-ci.org/rbberger/lammps-doc-utils)
[![Coverage Status](https://coveralls.io/repos/github/rbberger/lammps-doc-utils/badge.svg?branch=master)](https://coveralls.io/github/rbberger/lammps-doc-utils?branch=master)
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:
```python
extensions = [
...
'sphinxcontrib.images',
...
]
```
## Installation
1. Clone this repository
2. Install using setup.py
```bash
python setup.py install
```
## Usage
Convert .txt files using `txt2rst`:
```bash
# 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:
```html
<!-- 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
<!-- HTML_ONLY -->
<HEAD>
<TITLE>LAMMPS Users Manual</TITLE>
...
</HEAD>
<BODY>
<!-- END_HTML_ONLY -->
```
Event Timeline
Log In to Comment