docs: move index markdown files back to rst

canonical · Dec 16, 2024 · 737976c · 737976c
1 parent a654a9e
commit 737976c
Show file tree

Hide file tree

Showing 6 changed files with 47 additions and 126 deletions.
diff --git a/docs/explanation/#index.rst# b/docs/explanation/#index.rst#
diff --git a/docs/explanation/index.rst b/docs/explanation/index.rst
@@ -3,4 +3,16 @@
 Explanation
 ***********
 
-TBA
+As Charmcraft is a part of the `Juju Charm SDK <https://juju.is/docs/sdk>`_, most
+explanation is hosted on the `Charm SDK docs <https://juju.is/docs/sdk/explanation>`_.
+
+.. toctree::
+   :maxdepth: 1
+
+   /common/craft-parts/explanation/dump_plugin
+   /common/craft-parts/explanation/filesets
+   lifecycle
+
+
+`Charm SDK docs <https://juju.is/docs/sdk/explanation>`_
+========================================================
diff --git a/docs/howto/index.md b/docs/howto/index.md
diff --git a/docs/howto/index.rst b/docs/howto/index.rst
@@ -0,0 +1,26 @@
+.. _howto:
+
+How-To
+******
+
+.. toctree::
+   :maxdepth: 2
+
+   charm-to-poetry
+   charm-to-python
+   shared-cache
+   Manage the `charmcraft` CLI <manage-the-charmcraft-cli>
+   Manage charms <manage-charms>
+   Manage charms (12-factor apps) <manage-12-factor-app-charms>
+   Manage extensions <manage-extensions>
+   Manage resources <manage-resources>
+   Manage libraries <manage-libraries>
+   Manage parts <manage-parts>
+   Manage the current Charmhub user <manage-the-current-charmhub-user>
+   Manage names <manage-names>
+   Manage revisions <manage-revisions>
+   Manage channels <manage-channels>
+   Manage tracks <manage-tracks>
+   Manage icons <manage-icons>
+   Misc <misc/index>
+   Manage bundles <manage-bundles>
diff --git a/docs/index.md b/docs/index.md
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,11 +3,16 @@
 Charmcraft
 ==========
 
-Charmcraft is part of the `Juju Charm SDK <https://juju.is/docs/sdk>`_.
-Most of Charmcraft's documentation is available there.
+Charmcraft (``charmcraft``) is a tool designed to simplify the creation, building, and sharing of a `Juju charm <https://juju.is/docs/juju/charmed-operator>`_.
+
+When you initialise a charm with the `charmcraft` CLI, you automatically get all the crucial project files, pre-populated with helpful template content. These files are such that they can be `charmcraft`-packed right away; however, to make them meaningul for the application you are charming, you'll want to customise the YAML and [`ops`](https://juju.is/docs/sdk/ops)-powered Python in these files. For certain types of applications (Django, FastAPI, Flask, Go), if you initialise with a suitable ``charmcraft`` extension, things are even easier -- just tweak a few values in the YAML and you get a fully functioning charm. Either way, once you're pleased with what you've got, you can again use ``chamcraft`` to publish your charm on [Charmhub](https://charmhub.io/).
+
+You can create, build, and share a charm any way you want, but with ``charmcraft`` you get state-of-the-art results in record time.
+
+If you're a charm author, you *must* use ``charmcraft``!
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :hidden:
 
    tutorial/index