Tutorial 7: From an ADS query to a document with Python

This guide shows how to:

  1. query ADS with adsfolio,

  2. split first-authored vs co-authored papers,

  3. optionally merge a talks CSV (Google Sheets export),

  4. generate clean Markdown outputs for CV/publication documents.

You can later convert the Markdown files to LaTeX with minimal changes.

Files

  • Example script: docs/examples/build_cv_markdown.py

  • Outputs (default): cv_example_output/publications.md and cv_example_output/cv_bundle.md, plus cv_example_output/talks.md when you pass a talks CSV. The script writes them under the current directory (change this with --output-dir). The repository does not include sample outputs. run the script to generate them.

Prerequisites

  1. Set your ADS token:

export ADS_API_TOKEN="YOUR_TOKEN"

  1. Install dependencies (repo uses uv):

uv sync

This uses the project’s .venv. Never synchronize a shared environment. The script needs pandas only for talks from a CSV URL. Add it temporarily to that run with uv run --with pandas python docs/examples/build_cv_markdown.py --talks-csv-url 'https://example.org/talks.csv'. Use an actual CSV URL in place of the example. This leaves the package’s dependency declarations unchanged.

Quick Run

uv run python docs/examples/build_cv_markdown.py \
  --first-author-prefix "bach, y" \
  --me-target "Doe, J."

Set --query to your ADS query and --output-dir to choose a destination. The example performs live ADS queries and writes Markdown. It has no dry-run option. For a config-driven workflow that can print output without writing it, use adsfolio cv generate (its dry-run still queries ADS).

What the script does

  • Uses ADSClient.search.query_all(...) so you do not need to paginate manually.

  • Requests CV-relevant ADS fields (bibcode, title, author, year, citation_count, etc.).

  • Splits records by first_author prefix.

  • Formats publication entries with:

    • ADS abstract links

    • author highlighting

    • citation counts

    • optional status markers/comments

  • Optionally reads talks CSV and writes invited/contributed sections.

Customization points

In docs/examples/build_cv_markdown.py, edit:

  • DEFAULT_QUERY: your ADS search query.

  • HIGHLIGHT_BIBCODES: selected papers marker.

  • STUDENT_BIBCODES: student-led marker.

  • STATUS_BY_BIBCODE: per-paper notes like accepted/submitted status.

  • RenderConfig: marker symbols and author highlighting format.

Notes for LaTeX users

The generated files are Markdown so they are easy to inspect and diff. When you are ready:

  1. Convert with Pandoc:

pandoc cv_example_output/publications.md -o cv_example_output/publications.tex

  1. Or replace format_publication_markdown(...) / format_talk_markdown(...) with TeX emitters (your existing workflow already maps cleanly to this structure).

adsfolio already provides helpers that are LaTeX-friendly (for example format_title_latex, format_author_list_cv, format_journal).