Metadata-Version: 2.5
Name: briefpp
Version: 0.1.0
Summary: Brief++: header-only C++17 reports in multiple formats
Project-URL: Homepage, https://github.com/vrtulka23/briefpp
Project-URL: Documentation, https://vrtulka23.github.io/briefpp/
Project-URL: Source, https://github.com/vrtulka23/briefpp
Author: Brief++ contributors
License-Expression: MIT
License-File: LICENSE
Keywords: c++,header-only,html,latex,reports
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Brief++

A lightweight, embeddable C++17 library for generating technical and scientific reports in Markdown/MyST, reStructuredText/Sphinx, HTML, LaTeX, Typst, plain text, and JSON AST. The C++ core is header-only and has no external dependencies.

## Quick start

Add `include/` to your compiler's include path, or use the optional CMake target:

```cmake
add_subdirectory(external/briefpp)
target_link_libraries(application PRIVATE briefpp::briefpp)
```

```cpp
#include <briefpp/report.hpp>

int main() {
    briefpp::Document doc;
    doc.title("Simulation Report").author("Research Team");
    auto& results = doc.section("Results");
    results.paragraph().text("The simulation converged. See ")
        .reference("density-profile").text(" for the profile.");
    results.equation(R"(E = mc^2)", "energy");
    results.figure("density.png").caption("Density profile")
        .label("density-profile").width(0.8);
    results.table().columns("Parameter", "Value", "Unit")
        .row("Temperature", "273.15", "K");
    doc.write("report.md");
    doc.write("report.rst");
    doc.write("report.tex");
    doc.write("report.html");
    doc.write("report.typ");
    doc.write("report.txt");
    doc.write("report.json");
}
```

Run `cmake -S . -B build && cmake --build build && ctest --test-dir build` to build and test. The complete example is in [`examples/atmospheric.cpp`](examples/atmospheric.cpp).

To generate files you can inspect, run `cmake --build build --target briefpp_demo` after configuring. This creates all seven text formats in `build/demo` alongside the sample figure; with `pdflatex` installed, it also creates a PDF. Edit `examples/atmospheric.cpp` and run the target again to see your changes.

The standalone test build downloads doctest v2.5.3 through CMake FetchContent. When this repository is added as a subdirectory of another project, tests and examples default to off, so the header-only C++ library needs no download.

### PyPI header package

The optional `briefpp` Python distribution installs the same C++ headers; it does not provide Python bindings or add dependencies to the C++ library. After `pip install briefpp`, obtain the compiler include directory with `python -c 'import briefpp; print(briefpp.get_include())'`. Use that directory with your compiler's `-I` option so `#include <briefpp/report.hpp>` works.

To publish a version, update both `project.version` in `pyproject.toml` and the version in `CMakeLists.txt`, then publish a GitHub release tagged `v<version>` (for example, `v0.1.0`). The release workflow builds a wheel and source archive, checks the package, and uploads both to PyPI. Set the GitHub Actions secret `PYPI_API_TOKEN` to a PyPI API token before publishing. The first successful upload creates the PyPI project if the name is available.

## Supported subset

The semantic model supports metadata, nested sections, reusable inline content, citations, equations, figures, headered and headerless tables, nested lists, definition lists, code blocks, quotes, admonitions, horizontal rules, page breaks, IDs, semantic roles, backend-specific raw blocks, and reusable document fragments. Markdown output uses MyST directives for equations, figures, and admonitions. RST output targets Sphinx. LaTeX, HTML, and Typst renderers have small backend-specific configuration APIs; LaTeX can map roles to style-defined environments.

PDF compilation, parsing, and bibliography database management are outside the core. A `.tex` or `.typ` file can be compiled with an installed external tool. Figure files must exist at the paths used when rendering or compiling the report. See [renderer behavior and degradation](docs/backends.rst) for format-specific details.

The C++ API is documented in the [Sphinx documentation](docs/index.rst).

GitHub Actions runs the doctest suite and builds the Sphinx HTML website on pushes and pull requests. On pushes to `main`, it publishes the site to GitHub Pages after the tests pass. Enable **Settings → Pages → Build and deployment → GitHub Actions** in the repository once; the site will then be available at [vrtulka23.github.io/briefpp](https://vrtulka23.github.io/briefpp/). The `sphinx-site` artifact remains available from each workflow run.
