This directory contains the RST source files for OneCite's documentation, built with Sphinx.

Install the required documentation dependencies:

pip install -e ".[dev]"
# or
pip install sphinx sphinx-rtd-theme

To build the documentation as HTML:

# On Linux/macOS
make html

# On Windows (if make is not available)
sphinx-build -b html . _build/html

The built documentation will be in _build/html/. Open _build/html/index.html in your browser to view it.

PDF:

make latexpdf

Man Pages:

make man

Texinfo:

make texinfo

Epub:

make epub

To remove all built documentation:

make clean

docs/
├── conf.py                      # Sphinx configuration
├── index.rst                    # Main documentation index
├── installation.rst             # Installation guide
├── quick_start.rst              # Quick start guide
├── basic_usage.rst              # Basic usage guide
├── advanced_usage.rst           # Advanced usage guide
├── benchmarking.rst             # Benchmark suite and regression checks
├── cli_contracts.rst            # Stable CLI JSON/NDJSON contracts
├── onecite_skill.rst            # Workflow skill package guide
├── python_api.rst               # Python API guide
├── templates.rst                # Custom templates guide
├── output_formats.rst           # Output formats guide
├── faq.rst                      # Frequently asked questions
├── contributing.rst             # Contributing guidelines
├── changelog.rst                # Version changelog
├── api/
│   ├── core.rst                # Core API reference
│   ├── exceptions.rst          # Exception reference
│   └── pipeline.rst            # Pipeline reference
├── Makefile                     # Build automation
└── README.md                    # This file

• installation.rst - How to install OneCite
• quick_start.rst - Get started in 5 minutes
• basic_usage.rst - Basic usage examples

• advanced_usage.rst - Advanced features and techniques
• benchmarking.rst - Deterministic benchmarks and regression checks
• cli_contracts.rst - Stable JSON/NDJSON schemas and exit codes
• onecite_skill.rst - Using the bundled OneCite skill for automation
• python_api.rst - Using OneCite as a Python library
• templates.rst - Creating custom citation templates
• output_formats.rst - Understanding output formats

• api/core.rst - Core API documentation
• api/exceptions.rst - Exception reference
• api/pipeline.rst - Pipeline processing reference

• faq.rst - Frequently asked questions
• contributing.rst - Contribution guidelines
• changelog.rst - Version history and roadmap

Documentation is written in reStructuredText (RST) format. Here are some basics:

Main Section
============

Subsection
----------

Subsubsection
~~~~~~~~~~~~~

**Bold text** and *italic text*

.. code-block:: python

    # Code block
    import onecite
    
    result = onecite.process_references(
        "10.1038/nature14539", "txt", "journal_article_full",
        "bibtex"
    )

- Bullet list
- Another item
  - Nested item

1. Numbered list
2. Second item

:doc:`Link to file`
`External link <https://example.com>`_

1. Create a new .rst file in the appropriate directory
2. Add it to the .. toctree:: directive in index.rst or a parent document
3. Build the docs to verify

Use .. code-block:: for syntax-highlighted code:

.. code-block:: python

    from onecite import process_references
    
    result = process_references(
        "10.1038/nature14539",
        input_type="txt",
        template_name="journal_article_full",
        output_format="bibtex"
    )
    print('\n\n'.join(result['results']))

The Sphinx configuration is in conf.py. Key settings:

• Extensions - Enabled Sphinx extensions for autodoc, intersphinx, etc.
• Theme - Using the ReadTheDocs theme (sphinx-rtd-theme)
• HTML Output - Settings for the HTML theme
• Autodoc - Automatic API documentation generation

Documentation builds automatically on:

• GitHub Commits
• Pull Requests
• Releases

The documentation is hosted at:

• Main-branch documentation: https://hezhiang.com/OneCite/

The current workflow deploys this site from the main branch. It is not a separate, version-pinned “latest release” site; release documentation must not be inferred from this URL unless a release-specific deployment is added.

1. Fork the repository
2. Create a branch for your changes
3. Edit .rst files
4. Build locally to verify: make html
5. Submit a pull request

See contributing.rst for more details.

To create links within documentation:

:doc:`quick_start`           # Link to another document
:ref:`genindex`              # Link to generated index
:meth:`~onecite.process_references`  # Link to methods
:class:`~onecite.RawEntry`           # Link to classes

Tables:

==========  ============
Header 1    Header 2
==========  ============
Cell 1      Cell 2
Cell 3      Cell 4
==========  ============

Lists:

- Item 1
- Item 2
  - Subitem 2.1
  - Subitem 2.2
- Item 3

• Run make html frequently while editing
• Use sphinx-build -W to treat warnings as errors
• Use make linkcheck to verify all links
• Keep lines under 80 characters for easier reviewing

"make: command not found" on Windows:

# Install make for Windows or use sphinx-build directly
sphinx-build -b html . _build/html

Module not found errors:

# Ensure you're in the docs directory
cd docs

# Rebuild the documentation
make clean
make html

Theme not found:

# Install the theme
pip install sphinx-rtd-theme

For documentation issues:

1. Check the GitHub Issues
2. Search GitHub Discussions
3. See :doc:faq for common questions

The OneCite documentation is licensed under the MIT License. See LICENSE for details.