fix: remove APA/MLA (#31 #32), dead _complete_fields code (#29), fix conference detection (#28), Statement of Need (#7 #14), examples (#33), docs cleanup (#6 #20)

- #31 #32: remove APA/MLA formatters; only BibTeX output is supported
- #29: _complete_fields is now a no-op passthrough; removed _fetch_missing_field thread logic
- #28: treat CrossRef 'proceedings-article' type and booktitle field as conference entries
- #28: remove hardcoded 'arXiv preprint' journal from arXiv metadata
- #7: add Statement of Need section to README
- #14: add comparison table (OneCite vs Zotero/CrossRef/doi2bib) to README
- #33: add docs/examples/ with references.txt and existing.bib sample files
- #6: update README features table with accurate data source description
- #20: confirm URL branch logic is not duplicating queries post-refactor
- docs: remove APA/MLA from all documentation files
- tests: update all tests to reflect APA/MLA removal

Closes #31
Closes #32
Closes #29
Closes #28
Closes #7
Closes #14
Closes #33
Closes #6
Closes #20

Author: Ang

README.md

@@ -40,16 +40,33 @@
 
 ---
 
+## Statement of Need
+
+Researchers frequently accumulate reference lists in ad-hoc formats — DOIs copied from browser tabs, arXiv IDs from paper PDFs, titles typed by hand, and BibTeX fragments from various sources. Cleaning these into a consistent, complete `.bib` file is tedious and error-prone.
+
+OneCite solves this by accepting **any mix of identifiers and text queries** and automatically resolving them to structured BibTeX through a pipeline of academic APIs (CrossRef, arXiv, PubMed, Semantic Scholar, and others). It is designed for researchers who work primarily in the terminal, use LaTeX, and want a lightweight, scriptable tool — not a full reference manager.
+
+**When to use OneCite vs. alternatives:**
+
+| Tool | Best for |
+|---|---|
+| **OneCite** | One-shot conversion of messy reference lists to BibTeX in a terminal/script |
+| **Zotero** | Long-term reference management, GUI-based, browser integration |
+| **CrossRef API directly** | When you have clean DOIs and want canonical metadata |
+| **doi2bib** | Single DOI → BibTeX conversion, no fuzzy matching |
+
+---
+
 ## Features
 
 | Feature                 | Description                                                                                             |
 | ----------------------- | ------------------------------------------------------------------------------------------------------- |
 | **Fuzzy Matching**          | Match references against multiple academic databases even from incomplete or inaccurate info.         |
-| **Multiple Formats**        | Input `.txt`/`.bib` → Output **BibTeX**, **APA**, or **MLA**.                                         |
+| **Multiple Formats**        | Input `.txt`/`.bib` → Output **BibTeX**.                                                             |
 | **4-stage Pipeline**        | A 4-stage process (clean → query → validate → format) to produce consistent output.                  |
 | **Field Completion**        | Enrich entries by filling in missing fields like journal, volume, pages, and authors.                |
 | 🎓 **7+ Citation Types**    | Handles journal articles, conference papers, books, software, datasets, theses, and preprints.        |
-| **Domain-Aware Routing**    | Auto-detects content type and domain (Medical/CS/General) to pick the best data source.              |
+| **Multi-Source Lookup**     | Queries CrossRef, arXiv, PubMed, Semantic Scholar, Google Books, and others for every entry.         |
 | **Many Identifier Types**   | Accepts DOI, PMID, arXiv ID, ISBN, GitHub URL, Zenodo DOI, or plain text queries.                    |
 | 🎛️ **Interactive Mode**    | Manually select the correct entry when multiple potential matches are found.                          |
 | **Custom Templates**        | YAML-based templates to control which fields are collected and how entries are typed.                 |
@@ -144,14 +161,12 @@ Your `results.bib` file now contains entries of different types.
 ## 📖 Advanced Usage
 
 <details>
-<summary><strong>🎨 Multiple Output Formats (APA, MLA)</strong></summary>
+<summary><strong>Direct String and Stdin Input</strong></summary>
 
 ```bash
-onecite process refs.txt --output-format apa
-# → LeCun, Y., Bengio, Y., & Hinton, G. (2015). Deep learning. Nature, 521(7553), 436-444.
-
-onecite process refs.txt --output-format mla
-# → LeCun, Yann, Yoshua Bengio, and Geoffrey Hinton. "Deep Learning." Nature 521.7553 (2015): 436-444.
+onecite process "10.1038/nature14539"
+onecite process "Attention is all you need, Vaswani et al., NIPS 2017"
+echo "10.1038/nature14539" | onecite process -
 ```
 </details>
 

docs/advanced_usage.rst

@@ -102,19 +102,6 @@ To merge multiple `.bib` files::
 
     cat file1.bib file2.bib file3.bib > combined.bib
 
-Converting Between Formats
----------------------------
-
-Convert BibTeX to APA::
-
-    onecite process input.bib --output-format apa -o output.txt
-
-Convert APA to BibTeX::
-
-    # First save APA format in a parseable way, then convert back
-    onecite process references.txt --output-format apa -o apa_refs.txt
-    # Then process again to get BibTeX
-    onecite process original.txt -o output.bib
 
 Using with Git for Version Control
 -----------------------------------

docs/api/core.rst

@@ -27,7 +27,7 @@ The primary function for processing citations.
 - ``input_content`` (str): The reference content to process
 - ``input_type`` (str): Type of input - ``"txt"`` or ``"bib"`` (required)
 - ``template_name`` (str): Template name to use (e.g., ``"journal_article_full"``) (required)
-- ``output_format`` (str): Output format - ``"bibtex"``, ``"apa"``, or ``"mla"`` (required)
+- ``output_format`` (str): Output format - currently only ``"bibtex"`` is supported (required)
 - ``interactive_callback`` (Callable): Function to handle ambiguous matches. Takes a list of candidate dicts and returns the selected index (0-based), or -1 to skip (required)
 - ``use_google_scholar`` (bool): Enable Google Scholar as an additional data source. Requires the optional ``scholarly`` package. Default is ``False``.
 

docs/basic_usage.rst

@@ -53,26 +53,10 @@ OneCite can process various academic identifiers:
 Output Formats
 ~~~~~~~~~~~~~~
 
-**BibTeX (.bib)** - Default format::
+**BibTeX (.bib)** - The output format::
 
     onecite process refs.txt -o output.bib
 
-**APA** - American Psychological Association format::
-
-    onecite process refs.txt --output-format apa
-
-Example APA output::
-
-    LeCun, Y., Bengio, Y., & Hinton, G. (2015). Deep learning. Nature, 521(7553), 436-444.
-
-**MLA** - Modern Language Association format::
-
-    onecite process refs.txt --output-format mla
-
-Example MLA output::
-
-    LeCun, Yann, Yoshua Bengio, and Geoffrey Hinton. "Deep Learning." Nature 521.7553 (2015): 436-444.
-
 Command-Line Options
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -82,9 +66,7 @@ Command-Line Options
 
 **Output Format (--output-format)**::
 
-    onecite process input.txt --output-format apa
-    onecite process input.txt --output-format mla
-    onecite process input.txt --output-format bibtex  # default
+    onecite process input.txt --output-format bibtex  # only supported format
 
 **Interactive Mode (--interactive)**
 
@@ -154,16 +136,7 @@ Example 1: Process a BibTeX File
 This will read ``my_references.bib``, enhance the entries, and save to ``clean_references.bib``.
 The ``--input-type`` flag is optional for ``.bib`` files — OneCite detects the format automatically.
 
-Example 2: Convert to APA Format
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-::
-
-    onecite process references.txt --output-format apa -o output.txt
-
-This will process references and output them in APA format.
-
-Example 3: Interactive Processing
+Example 2: Interactive Processing
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
@@ -172,7 +145,7 @@ Example 3: Interactive Processing
 
 This will allow you to manually verify and select the correct match for each reference.
 
-Example 4: Quick Check Without Saving
+Example 3: Quick Check Without Saving
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ::
@@ -181,6 +154,19 @@ Example 4: Quick Check Without Saving
 
 This will show you the processed results without saving to a file.
 
+Example Files
+-------------
+
+Ready-to-use example input files are in ``docs/examples/``:
+
+- ``references.txt`` — mixed identifiers and text queries (one entry per blank-separated block)
+- ``existing.bib`` — a BibTeX file to be enriched
+
+To run them::
+
+    onecite process docs/examples/references.txt -o results.bib
+    onecite process docs/examples/existing.bib -o enriched.bib
+
 Next Steps
 ----------
 

docs/examples/existing.bib

@@ -0,0 +1,15 @@
+@article{LeCun2015,
+  title={Deep learning},
+  author={LeCun, Yann and Bengio, Yoshua and Hinton, Geoffrey},
+  journal={Nature},
+  year={2015},
+  volume={521},
+  pages={436-444}
+}
+
+@inproceedings{Vaswani2017,
+  title={Attention Is All You Need},
+  author={Vaswani, Ashish and Shazeer, Noam and Parmar, Niki},
+  booktitle={Advances in Neural Information Processing Systems},
+  year={2017}
+}

docs/examples/references.txt

@@ -0,0 +1,9 @@
+10.1038/nature14539
+
+Attention is all you need, Vaswani et al., NIPS 2017
+
+Goodfellow, I., Bengio, Y., & Courville, A. (2016). Deep Learning. MIT Press.
+
+https://github.com/tensorflow/tensorflow
+
+arXiv:2103.00020

onecite/cli.py

@@ -85,7 +85,7 @@ def create_parser() -> argparse.ArgumentParser:
     )
     process_parser.add_argument(
         '--output-format',
-        choices=['bibtex', 'apa', 'mla'],
+        choices=['bibtex'],
         default='bibtex',
         help='Output format (default: bibtex)'
     )