Development

Contributor workflow for the biblioflow monorepo.

Monorepo layout

packages/
├── biblioflow/                 # Core Python library and CLI
├── biblioflow-web/
│   ├── backend/                # FastAPI package published as biblioflow-web
│   └── frontend/               # Private React/Vite app bundled into backend
└── biblioflow-nb/              # Jupyter/Colab widget package

Top-level project files coordinate documentation, CI, release automation, and Makim tasks.

Environment setup

conda env create -f conda/dev.yaml
conda activate biblioflow
cd packages/biblioflow
poetry config virtualenvs.create false
poetry install --extras "dev yaml"

Core library checks

makim tests.linter
makim tests.unit
makim package.build

The linter task runs pre-commit hooks, including Ruff, Mypy, and Douki for core library docstrings.

Source loader development

Source-specific import behavior belongs in packages/biblioflow, not in the web or notebook applications. The current loader stack is organized around:

• biblioflow/load/infer.py for source/format aliasing and detection.
• biblioflow/load/dispatcher.py for bf.load(...) orchestration.
• biblioflow/io/ for file readers such as BibTeX, RIS, and Web of Science.
• biblioflow/providers/adapters.py for provider-specific mappings.
• biblioflow/normalize/ for DOI, date, author, text, and reference helpers.
• biblioflow/sources/ for public source helpers such as from_openalex(...), from_crossref(...), from_scopus(...), from_pubmed(...), and from_pmc(...).

Add fixtures under packages/biblioflow/tests/fixtures/<source>/ and cover:

• detection,
• field mapping,
• raw payload preservation,
• missing or partial fields,
• unicode and multiline values,
• API normalizers without live network calls.

For PubMed and PubMed Central support, use fake pymedx.PubMed and pymedx.PubMedCentral clients in unit tests. Do not add default CI tests that query NCBI directly. If a live check is needed, make it opt-in and require BIBLIOFLOW_NCBI_EMAIL.

Web checks

makim web.backend.tests
makim web.frontend.install
makim web.frontend.lint
makim web.frontend.tests
makim web.frontend.build
makim web.package.build

The frontend is private but still participates in CI because it is bundled into the published biblioflow-web Python package.

Notebook checks

makim nb.tests
makim nb.package.build
makim nb.examples.check

Documentation checks

The documentation site is built with Quarto:

makim docs.build

The Quarto source lives in docs/ and renders to build/.

Full CI workflow

makim all.ci

CI also runs on supported Python versions and builds all three Python packages.

Documentation style

• Keep user-facing docs in docs/*.qmd.
• Prefer short runnable examples and explicit package names.
• Document new public APIs when adding them to the core package.
• Keep web and notebook documentation clear that they delegate computation to the core biblioflow library.
• Avoid documenting unsupported aliases such as biblio-flow.

Douki docstrings

Core library Python docstrings are validated by Douki. Docstrings must be YAML dictionaries with a title field, for example:

def example(path: str) -> str:
    """
    title: Return a normalized path string.
    parameters:
      path:
        type: str
        description: Input path.
    returns:
      type: str
    """
    return path

Run the hook directly with:

pre-commit run douki --all-files