Repository Layout
=================

ThornForge is designed to build other repositories without requiring a
ThornForge-specific configuration file. Discovery is based on conventional file
locations and project metadata.

Documentation source discovery
------------------------------

The builder searches for a Sphinx ``conf.py`` in this order:

1. ``docs/``
2. ``docs/source/``
3. ``doc/``
4. ``doc/source/``
5. ``documentation/``
6. ``documentation/source/``

If none of those paths contains ``conf.py``, ThornForge recursively searches for
the shallowest remaining ``conf.py`` while skipping transient directories such as
``.git``, virtual environments, build outputs, and caches.

Project name discovery
----------------------

The display name comes from the first available source:

1. ``[project].name`` in ``pyproject.toml``
2. ``[tool.poetry].name`` in ``pyproject.toml``
3. ``name`` in ``package.json``
4. The repository directory name

Version discovery
-----------------

Git repositories are built from tags matching ``v*`` when such tags exist. Tags
are sorted using PEP 440 version parsing after the leading ``v`` is removed.

Repositories without matching tags get one build using a fallback label:

1. ``[project].version`` in ``pyproject.toml``
2. ``git describe --tags --always``
3. ``current``

Project pages
-------------

Known top-level metadata files are rendered as root-level pages in the generated
site. Supported candidates include ``README.rst``, ``README.txt``,
``README.html``, ``CHANGELOG.rst``, ``HISTORY.rst``, and ``RELEASES.rst``.