Improve docs: use tables for topics/domains, order core first

Replace definition lists with tables in Sphinx documentation for better
readability. Sort topics with core first, then alphabetically.

Author: jensens

CHANGES.md

@@ -1,8 +1,9 @@
 # Changelog
 
-## 2.0.1 (unreleased)
+## 2.0.1
 
-- nothing yet
+- Enhancement: Use tables in the generated sphinx code for topic/domains.
+  [jensens, 02-11-2025]
 
 ## 2.0.0 (2025-10-24)
 

src/mxmake/templates.py

@@ -377,6 +377,8 @@ class Topics(Template):
     @property
     def template_variables(self) -> dict[str, typing.Any]:
         topics = load_topics()
+        # Sort topics: core first, then alphabetically by name
+        topics = sorted(topics, key=lambda t: (t.name != "core", t.name))
         return {"topics": topics}
 
     def render(self):
@@ -406,6 +408,8 @@ class Dependencies(Template):
     @property
     def template_variables(self) -> dict[str, typing.Any]:
         topics = load_topics()
+        # Sort topics: core first, then alphabetically by name
+        topics = sorted(topics, key=lambda t: (t.name != "core", t.name))
         return {"topics": topics}
 
     def render(self):

src/mxmake/templates/topics.md

@@ -13,42 +13,32 @@
 
 {{ domain.description }}
 
-FQN
-: `{{ domain.fqn }}`
-
-{% if domain.depends %}
-Depends on
-{% for depend in domain.depends %}
-: `{{ depend }}`
-{% endfor %}
-{% endif %}
-
-{% if domain.soft_depends %}
-Soft depends on
-{% for soft_depends in domain.soft_depends %}
-: `{{ soft_depends }}`
-{% endfor %}
+| Property | Value |
+|----------|-------|
+| **FQN** | `{{ domain.fqn }}` |
+{% if domain.depends or domain.soft_depends %}
+| **Dependencies** | {% if domain.depends %}**Hard:** {% for depend in domain.depends %}`{{ depend }}`{% if not loop.last %}, {% endif %}{% endfor %}{% if domain.soft_depends %}<br>{% endif %}{% endif %}{% if domain.soft_depends %}**Soft:** {% for soft_depend in domain.soft_depends %}`{{ soft_depend }}`{% if not loop.last %}, {% endif %}{% endfor %}{% endif %} |
 {% endif %}
 
 {% if domain.targets %}
-Targets
-{% for target in domain.targets %}
-: `{{ target.name }}`
 
-  : {{ target.description | indent(4) }}
+**Targets:**
 
+| Target | Description |
+|--------|-------------|
+{% for target in domain.targets %}
+| `{{ target.name }}` | {{ target.description | replace('\n', '<br>') }} |
 {% endfor %}
 {% endif %}
 
 {% if domain.settings %}
-Settings
-{% for setting in domain.settings %}
-: `{{ setting.name }}`
 
-  : {{ setting.description | indent(4) }}
-
-  : Default: `{{ setting.default | indent(4) }}`
+**Settings:**
 
+| Setting | Description | Default |
+|---------|-------------|---------|
+{% for setting in domain.settings %}
+| `{{ setting.name }}` | {{ setting.description | replace('\n', '<br>') }} | `{{ setting.default }}` |
 {% endfor %}
 {% endif %}