Metadata-Version: 2.4
Name: aastex
Version: 0.4.0
Summary: A Python wrapper around the AASTeX Latex packages
Author-email: "Roy T. Smart" <roytsmart@gmail.com>
Project-URL: Homepage, https://github.com/sun-data/aastex
Project-URL: Documentation, https://aastex.readthedocs.io/en/latest
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pylatex
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: astropy
Provides-Extra: test
Requires-Dist: pytest; extra == "test"
Provides-Extra: doc
Requires-Dist: pytest; extra == "doc"
Requires-Dist: graphviz; extra == "doc"
Requires-Dist: sphinx-autodoc-typehints; extra == "doc"
Requires-Dist: pydata-sphinx-theme; extra == "doc"
Requires-Dist: ipykernel; extra == "doc"
Requires-Dist: jupyter-sphinx; extra == "doc"
Requires-Dist: sphinx-favicon; extra == "doc"

# aastex

[![tests](https://github.com/sun-data/aastex/actions/workflows/tests.yml/badge.svg)](https://github.com/sun-data/aastex/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/sun-data/aastex/graph/badge.svg?token=c9VYZtRAO8)](https://codecov.io/gh/sun-data/aastex)
[![Black](https://github.com/sun-data/aastex/actions/workflows/black.yml/badge.svg)](https://github.com/sun-data/aastex/actions/workflows/black.yml)
[![Documentation Status](https://readthedocs.org/projects/aastex/badge/?version=latest)](https://aastex.readthedocs.io/en/latest/?badge=latest)
[![PyPI version](https://badge.fury.io/py/aastex.svg)](https://badge.fury.io/py/aastex)

Write AAS journal articles as Python programs.

This library extends [PyLaTeX](https://github.com/JelteF/PyLaTeX) with the pieces of the
[AASTeX](https://journals.aas.org/aastex-package-for-manuscript-preparation/) class used by
the journals of the American Astronomical Society: titles, authors and their affiliations,
acronyms, sections, figures, and bibliographies.

## Why write a paper as a program?

In a normal manuscript, the numbers in the prose and the figures beside them are copied
from an analysis by hand, and they start drifting from that analysis the moment it changes.
Writing the article as a program removes the copying step: figures are generated by the
same code that produced the result, and quantities are defined as LaTeX macros computed
from Python values, so the text cannot disagree with the analysis behind it.

```python
doc.set_variable_quantity(
    name="speedOfLight",
    value=astropy.constants.c.to(u.km / u.s),
    scientific_notation=True,
)
```

The prose then refers to `\speedOfLight`, and the compiled article shows whatever the code
computed, correctly formatted with its units.

## Installation

`aastex` is available on PyPI and can be installed using `pip`:

```bash
pip install aastex
```

Compiling an article also requires a LaTeX installation providing the AASTeX class
dependencies. On Debian and Ubuntu:

```bash
sudo apt-get install texlive-publishers texlive-science cm-super latexmk
```

## Getting started

```python
import pathlib
import aastex

doc = aastex.Document()
doc.append(aastex.Title("An Interesting Article"))
doc += [
    aastex.Author(
        name="Jane Doe",
        affiliation=aastex.Affiliation("Fancy University"),
        email="jane.doe@fancy.edu",
    )
]

section = aastex.Section("Introduction")
section.append("Some text.")
doc.append(section)

doc.generate_pdf(pathlib.Path("an_interesting_article"))
```

The [documentation](https://aastex.readthedocs.io/en/latest/) walks through a complete
example that adds figures, acronyms, computed variables, and a bibliography.

## What the library provides

- **`Document`** — the article itself. `generate_pdf()` writes the `.tex` file, saves every
  figure beside it, copies in the AASTeX class and bibliography style, and compiles the
  result.
- **`Title`, `Author`, `Affiliation`, `Abstract`, `Section`** — the parts of a manuscript,
  which can be referenced from the prose by formatting them into a string, so section and
  figure numbers are never written by hand.
- **`Figure`, `FigureStar`, `Fig`, `Gridline`** — figures built directly from
  [matplotlib](https://matplotlib.org/) figures via `add_fig()`, or from existing image
  files via `add_image()`.
- **`Variable`** — a numeric value from the analysis, exposed to the prose as a LaTeX macro.
- **`Acronym`** — an acronym that expands on first use and is abbreviated afterwards.
- **`Bibliography`** — the reference list, from a BibTeX file.

## Preparing a submission

The [AAS submission system](https://journals.aas.org/pre-submission-checklist-for-aas-journal-authors/)
requires every file of a manuscript at the same directory level, since it cannot parse
subdirectories. `Document.generate_archive()` compiles the article and collects the `.tex`
file, the `.bbl` file required by the AAS conversion software, the class and bibliography
style files, and every figure into a flat archive ready to upload:

```python
doc.generate_archive(pathlib.Path("an_interesting_article"), bibliography="sources.bib")
```
