Metadata-Version: 2.4
Name: rsm-markup
Version: 0.4.0
Summary: ReStructured Manuscripts (RSM) markup language
Author-email: Leo Torres <leo@leotrs.com>
License: Copyright 2022 leotrs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
        
Project-URL: Homepage, https://write-rsm.org/
Keywords: markup,science,publishing,static site generator
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: fs>=2.4.15
Requires-Dist: icecream>=2.1.2
Requires-Dist: livereload>=2.6.3
Requires-Dist: pygments>=2.14.0
Requires-Dist: tree-sitter>=0.23.2
Requires-Dist: tree-sitter-rsm>=0.6.0
Requires-Dist: ujson>=5.10.0
Provides-Extra: dev
Requires-Dist: mypy>=1.16.1; extra == "dev"
Requires-Dist: mypy-extensions>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=2.20.0; extra == "dev"
Requires-Dist: pytest>=7.1.1; extra == "dev"
Requires-Dist: pytest-sugar>=0.9.6; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: types-pygments>=2.19.0; extra == "dev"
Requires-Dist: types-ujson>=5.6.0; extra == "dev"
Provides-Extra: doc
Requires-Dist: Sphinx>=6.2.0; extra == "doc"
Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "doc"
Requires-Dist: sphinx-copybutton>=0.5.1; extra == "doc"
Requires-Dist: sphinx-design>=0.5.0; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints>=1.19.5; extra == "doc"
Requires-Dist: pydata-sphinx-theme>=0.12.0; extra == "doc"
Dynamic: license-file

# Readable Science Markup (RSM)

[![tests](https://github.com/leotrs/rsm/actions/workflows/test.yml/badge.svg)](https://github.com/leotrs/rsm/actions/workflows/test.yml)
[![docs](https://readthedocs.org/projects/rsm-markup/badge/?version=latest)](https://rsm-markup.readthedocs.io/en/latest/?badge=latest)

The web-first authoring software for scientific manuscripts.

RSM is a suite of tools that aims to change the way scientific manuscripts are published
and shared using modern web technology. Currently, most scientific publications are made
with LaTeX and published in PDF format. While the capabilities of LaTeX and related
software are undeniable, there are many pitfalls. RSM aims to cover this gap by allowing
authors to create web-first manuscripts that enjoy the benefits of the modern web.

One of the main aims of the RSM suite is to provide scientists with tools to author
scientific manuscripts in a format that is web-ready in a transparent, native way that
is both easy to use and easy to learn.  In particular, RSM is a suite of tools that
allow the user to write a plain text file (in a special `.rsm` format) and convert the
file into a web page (i.e. a set of .html, .css, and .js files).  These files can then
be opened natively by any web browser on any device.

+ Learn more in the [official website](https://www.write-rsm.org).
+ Try it out in the [online editor](https://lets.write-rsm.org).
+ Get started with the [docs](https://docs.write-rsm.org).


## Contributing

This project is under constant development and contributions are *very much* welcome!
Please develop your feature or fix in a branch and submit a PR.


### Rebuilding the Standalone JS Bundle

The file `rsm/static/rsm-standalone.js` is a pre-built bundle of all RSM JavaScript
for standalone HTML files (files that can be opened directly from `file://` URLs).

If you modify any JS files in `rsm/static/`, you must regenerate this bundle:

```bash
npx esbuild rsm/static/onload.js --bundle --format=iife --global-name=RSM --outfile=rsm/static/rsm-standalone.js
```

This bundles `onload.js` and all its dependencies into a single IIFE that exposes
`RSM.onload()` and `RSM.onrender()`. The bundle is committed to the repo so there's
no runtime dependency on esbuild.


## Development Setup

### Prerequisites
- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) - Fast Python package installer
- [just](https://just.systems/) - Command runner

### Installation

#### Install uv
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv
```

#### Install just
```bash
# macOS
brew install just

# Linux
cargo install just

# Windows
scoop install just
```

#### Clone and install rsm-markup
```bash
git clone --recurse-submodules https://github.com/leotrs/rsm.git
cd rsm
just install
```

This installs:
- `rsm-markup` in editable mode (you can modify the code)
- `tree-sitter-rsm` from PyPI as a pre-built wheel (compiled grammar)
- All development and documentation dependencies

**Note:** The `tree-sitter-rsm` grammar is installed from PyPI with platform-specific
pre-built binaries. You don't need to build anything unless you're modifying the grammar itself.

### Common Tasks
```bash
just                  # List all available commands
just test             # Run fast tests
just test-all         # Run all tests including slow ones
just lint             # Format code and run linter
just check            # Run lint + tests (quality gate)
just docs-serve       # Serve docs with live reload
```

### Grammar Development

**Most developers don't need this.** Only use these steps if you're modifying the
tree-sitter grammar in `tree-sitter-rsm/grammar.js`.

```bash
# Install tree-sitter-rsm in editable mode (overrides PyPI version)
just install-local

# After modifying grammar.js in tree-sitter-rsm/
just build-grammar
```

The difference between `just install` and `just install-local`:

| Command | `tree-sitter-rsm` source | Editable? | Use when |
|---------|--------------------------|-----------|----------|
| `just install` | PyPI wheel | No | Developing rsm-markup code (most common) |
| `just install-local` | Local submodule | Yes | Modifying the grammar itself |

## Publishing

This project uses `uv` for dependency management and `just` for task automation.

To release a new version to PyPI:

1. Update version in `pyproject.toml`
2. Create a git tag: `git tag v0.3.3 && git push origin v0.3.3`
3. Publish: `just publish`

Or use the GitHub Actions workflow by creating a release on GitHub.
