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.
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¶
- Make the document graph correct. Check the root, suffixes, exclusions, and includes.
- Make the references correct. Check domains, inventories, and custom object types.
- 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 Compatibility with Sphinx for the supported surface and the CPython, Django, and Flask evidence. See Declaring object types for declarative custom objects.