Move a Sphinx project
=====================

Guidedog follows Sphinx's project shape and many of its setting names.
It does not run ``conf.py`` or Python extensions.
Migration starts by separating data from executable configuration.

.. code-block:: sh

   guidedog migrate path/to/conf.py
   guidedog build html path/to/docs --diagnostics=json

``migrate`` reads literal settings and writes ``conf.toml``.
It reports computed values that need a human choice.
It does not import your project or run Python to discover those values.
Inspect the resulting configuration before treating it as equivalent.

Work in three passes
--------------------

1. Make the document graph correct. Check the root, suffixes, exclusions, and includes.
2. Make the references correct. Check domains, inventories, and custom object types.
3. Make the presentation correct. Check templates, diagrams, mathematics, and both outputs.

An unknown directive may belong to a project's private extension.
A successful HTML build does not prove that the private semantics were reproduced.
Read its diagnostics. Decide whether to replace the directive, configure a supported
alias, or retain a documented limitation.

See :doc:`../compatibility` for the supported surface and the CPython,
Django, and Flask evidence. See :doc:`../object-types` for declarative custom objects.