Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vberlier/docutils
Simple javascript parser for docutils xml documents.
https://github.com/vberlier/docutils
docutils parser restructuredtext sphinx xml
Last synced: 3 months ago
JSON representation
Simple javascript parser for docutils xml documents.
- Host: GitHub
- URL: https://github.com/vberlier/docutils
- Owner: vberlier
- License: mit
- Created: 2019-03-10T16:05:35.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-07T04:04:25.000Z (about 2 years ago)
- Last Synced: 2024-10-26T11:21:58.315Z (4 months ago)
- Topics: docutils, parser, restructuredtext, sphinx, xml
- Language: JavaScript
- Homepage:
- Size: 832 KB
- Stars: 3
- Watchers: 2
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# docutils
[](https://travis-ci.com/vberlier/docutils)
[](https://www.npmjs.com/package/docutils)
> Simple javascript parser for docutils xml documents.
This package uses [sax-js](https://github.com/isaacs/sax-js) to parse and turn [docutils xml documents](http://docutils.sourceforge.net/docs/ref/doctree.html) into plain javascript objects. This can be useful for working with documentation generated by tools like [sphinx](http://www.sphinx-doc.org).
```js
const docutils = require("docutils");
const document = docutils.parse(`
Hello, world!
`);
console.log(document.children[0].children[0]);
// Output: { tag: 'title', attributes: {}, children: [ 'Hello, world!' ] }
```
## Installation
You can install `docutils` with your `npm` client of choice.
```bash
$ npm install docutils
```
## Usage
### docutils.parse(string, plugins = [])
Parse the input string and return a hierarchy of plain javascript objects. The function will throw an error if the input string isn't valid xml.
Here's what the function would've returned in the previous example:
```js
{
tag: 'document',
attributes: {
source: '.../hello.rst'
},
children: [
{
tag: 'section',
attributes: {
ids: 'hello-world',
names: 'hello, world!'
},
children: [
{
tag: 'title',
attributes: {},
children: [
'Hello, world!'
]
}
]
}
]
}
```
Elements are turned into plain javascript objects with a specific structure:
- The `tag` property is the name of the element
- The `attributes` property is an object mapping each attribute name to its value
- The `children` property is an array that can contain strings and other elements
Keep in mind that you might need to catch parsing errors where appropriate:
```js
try {
docutils.parse("invalid document");
} catch (err) {
console.log(err);
// Error: Start tag expected, '<' not found
}
```
#### Plugins
The second argument of the `docutils.parse()` function is an optional array of plugins. Plugins are functions that take an instance of `docutils.DocumentParser` as parameter.
```js
const titleToUpperCase = (parser) => {
parser.on("element:title", (element) => {
element.children[0] = element.children[0].toUpperCase();
});
};
const document = docutils.parse(string, [titleToUpperCase]);
console.log(document.children[0].children[0]);
// Output: { tag: 'title', attributes: {}, children: [ 'HELLO, WORLD!' ] }
```
### docutils.DocumentParser({ plugins = [] } = {})
It's probably a good idea to always use the `docutils.parse()` function directly, but it's also possible to instantiate the parser manually.
```js
const parser = new docutils.DocumentParser();
const document = parser.parse(string);
```
Most of the time, you'll only interact with the parser through plugins. The `docutils.DocumentParser` class inherits from the nodejs [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter) and lets you hook into various stages of the parsing process.
| Event | Arguments | Description |
| ------------------ | ---------- | ------------------------------------------ |
| `document:start` | | Emitted before parsing a document |
| `document:end` | `document` | Emitted after parsing a document |
| `element` | `element` | Emitted after parsing an element |
| `element:TAG_NAME` | `element` | Emitted after parsing a `TAG_NAME` element |
## Contributing
Contributions are welcome. This project uses [jest](https://jestjs.io/) for testing.
```bash
$ npm test
```
The code follows the [javascript standard](https://standardjs.com/) style guide.
```bash
$ npm run lint
```
---
License - [MIT](https://github.com/vberlier/docutils/blob/master/LICENSE)