..
   This file is AUTO-GENERATED by Introligo.
   DO NOT EDIT manually - changes will be overwritten.
   To modify this documentation, edit the source YAML configuration
   and regenerate using: python -m introligo <config.yaml> -o <output_dir>

📖 Complete Getting Started Guide
=================================

5-minute guide to unified documentation with step-by-step instructions


Overview
--------

A comprehensive guide that walks you through setting up Introligo from installation
to building your first documentation hub. Includes common patterns, troubleshooting,
and tips for success.





















































Getting Started with Introligo
------------------------------


**5-minute guide to unified documentation.**


What You'll Build
~~~~~~~~~~~~~~~~~


By the end of this guide, you'll have:
- ✅ All your docs automatically discovered
- ✅ Professional Sphinx documentation site
- ✅ Beautiful theme with search
- ✅ Automatic navigation
- ✅ One command to rebuild everything


Prerequisites
~~~~~~~~~~~~~


- Python 3.8+
- A project with some documentation (READMEs, markdown files, etc.)


Step 1: Install (1 minute)
~~~~~~~~~~~~~~~~~~~~~~~~~~



.. code-block:: bash

   pip install PyYAML jinja2 sphinx furo


That's all you need!


Step 2: Create Configuration (2 minutes)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~


Create `introligo_config.yaml` in your project root:


.. code-block:: yaml

   # Minimal configuration - let Introligo do the work!
   index:
     title: "My Project Docs"
   
   discovery:
     enabled: true
     auto_include:
       readme: true
       changelog: true
       markdown_docs: "docs/**/*.md"
   
   sphinx:
     project: "My Project"
     html_theme: "furo"


**That's it!** This finds all your READMEs, CHANGELOG, and markdown files.


Step 3: Generate Documentation (2 minutes)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~



.. code-block:: bash

   # Generate docs
   python -m introligo introligo_config.yaml -o my_docs -v
   
   # Build with Sphinx
   cd my_docs
   sphinx-build -b html . _build/html
   
   # View it!
   python -m http.server 8000 --directory _build/html


Open http://localhost:8000 in your browser. **Done!** 🎉


What Just Happened?
~~~~~~~~~~~~~~~~~~~


1. **Discovery**: Introligo scanned your project
2. **Organization**: Docs were categorized automatically
3. **Generation**: RST files were created
4. **Building**: Sphinx created the HTML site

All from one simple config file!


Next Steps
~~~~~~~~~~



Add More Documentation Types
^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. code-block:: yaml

   discovery:
     enabled: true
     auto_include:
       readme: true
       changelog: true
       contributing: true  # Add CONTRIBUTING.md
       license: true       # Add LICENSE
       markdown_docs: "docs/**/*.md"



Add API Documentation
^^^^^^^^^^^^^^^^^^^^^


For Python projects:


.. code-block:: yaml

   discovery:
     enabled: true
     auto_include:
       readme: true
   
   modules:
     api:
       title: "API Reference"
       module: "myproject"  # Your package name



Customize Theme
^^^^^^^^^^^^^^^



.. code-block:: yaml

   sphinx:
     project: "My Project"
     html_theme: "furo"
     palette: "celin"  # Beautiful cosmic colors!
   
     html_theme_options:
       sidebar_hide_name: false



Exclude Unwanted Files
^^^^^^^^^^^^^^^^^^^^^^



.. code-block:: yaml

   discovery:
     enabled: true
     auto_include:
       markdown_docs: "docs/**/*.md"
   
     exclude_patterns:
       - "node_modules"
       - ".venv"
       - "build"
       - "test_*"



Common Patterns
~~~~~~~~~~~~~~~



Pattern 1: Simple Open Source Project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. code-block:: yaml

   index:
     title: "📚 My Library Docs"
   
   discovery:
     enabled: true
     auto_include:
       readme: true
       changelog: true
       contributing: true
       license: true
   
   modules:
     api:
       module: "mylib"
   
   sphinx:
     project: "MyLib"
     html_theme: "furo"
     palette: "celin"



Pattern 2: Documentation-Heavy Project
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. code-block:: yaml

   index:
     title: "Complete Docs"
   
   discovery:
     enabled: true
     scan_paths:
       - "."
       - "docs/"
       - "guides/"
     auto_include:
       readme: true
       changelog: true
       markdown_docs: "**/*.md"
   
   sphinx:
     project: "My Project"
     html_theme: "furo"



Pattern 3: API-Focused Library
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^



.. code-block:: yaml

   index:
     title: "API Documentation"
   
   discovery:
     enabled: true
     auto_include:
       readme: true
       changelog: true
   
   modules:
     api:
       title: "API Reference"
       module: "mypackage"
   
     examples:
       title: "Examples"
       file_includes:
         - "examples/basic.md"
         - "examples/advanced.md"
   
   sphinx:
     project: "MyPackage"
     html_theme: "furo"



Troubleshooting
~~~~~~~~~~~~~~~



"No module named 'introligo'"
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^


Install in development mode:

.. code-block:: bash

   pip install -e .


Or use full path:

.. code-block:: bash

   python -m introligo.introligo config.yaml -o docs



"No modules found"
^^^^^^^^^^^^^^^^^^


Check your `discovery` section:

.. code-block:: yaml

   discovery:
     enabled: true  # Make sure this is true!
     auto_include:
       readme: true  # At least one should be true



Docs not appearing
^^^^^^^^^^^^^^^^^^


Run with verbose output to see what's discovered:

.. code-block:: bash

   python -m introligo config.yaml -o docs -v


Look for lines like:

.. code-block:: text

   INFO: 📄 Found README: README.md
   INFO: 📅 Found CHANGELOG: CHANGELOG.md



Wrong categorization
^^^^^^^^^^^^^^^^^^^^


Override with manual modules:

.. code-block:: yaml

   discovery:
     enabled: true
     auto_include:
       markdown_docs: "docs/**/*.md"
   
   modules:
     my_guide:  # Manually control this one
       title: "Special Guide"
       file_includes: "docs/special.md"



Tips for Success
~~~~~~~~~~~~~~~~



1. Start Small
^^^^^^^^^^^^^^


Begin with just READMEs:

.. code-block:: yaml

   discovery:
     enabled: true
     auto_include:
       readme: true


Then add more types incrementally.


2. Use Verbose Mode
^^^^^^^^^^^^^^^^^^^


Always use `-v` while learning:

.. code-block:: bash

   python -m introligo config.yaml -o docs -v


You'll see exactly what's being discovered and categorized.


3. Preview Before Building
^^^^^^^^^^^^^^^^^^^^^^^^^^


Use dry-run to see what would be generated:

.. code-block:: bash

   python -m introligo config.yaml -o docs --dry-run



4. Keep Docs Where They Are
^^^^^^^^^^^^^^^^^^^^^^^^^^^


Don't reorganize your docs for Introligo. It finds them wherever they are!


5. Mix Auto and Manual
^^^^^^^^^^^^^^^^^^^^^^


Use discovery for common files, manual modules for special cases:


.. code-block:: yaml

   discovery:
     enabled: true
     auto_include:
       readme: true
   
   modules:
     architecture:  # Special case
       title: "Architecture"
       file_includes: "docs/architecture.md"



What's Next?
~~~~~~~~~~~~


Now that you have basic docs working:

1. **Explore Examples**: Check [`examples/`](examples/) for real-world configs
2. **Read the Guide**: See :doc:`EXAMPLES.md <examples/EXAMPLES>` for detailed patterns
3. **Customize Theme**: Try different palettes and themes - see :doc:`Theme Motifs Guide <theme_motifs>`
4. **Preview Themes**: Use `python docs/preview.py --motive <theme>` to test different color palettes
5. **Add API Docs**: Include autodoc for your code
6. **Share**: Publish to Read the Docs or GitHub Pages


Need Help?
~~~~~~~~~~


- **Examples**: [`examples/`](examples/) directory
- **Issues**: `GitHub Issues <https://github.com/JakubBrzezo/introligo/issues>`_
- **Architecture**: :doc:`HUB_ARCHITECTURE.md <HUB_ARCHITECTURE>` for technical details

---

**Ready to unite your docs?** Start with the minimal config above and build from there! 🚀