doc: Write about first impression

doc/conf.py

@@ -8,8 +8,10 @@
 
 # -- General configuration
 extensions = [
+    "rst_multi_refs.sphinx",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
+    "sphinx_tabs.tabs",
 ]
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

doc/index.rst

@@ -4,12 +4,31 @@ Home
 
 ``rst-multi-refs`` is referencing support library for Sphinx users.
 
+Base concept
+============
+
+This provides these features:
+
+* Support functions kit about creating custom roles to refer package registry for reStructuredText and Sphinx.
+* Custom roles to refer major package registry (`PyPI <https://pypi.org>`_, `npm <https://www.npmjs.com/>`_ and more ...).
+
+You can use this by :doc:`easy operation <./usage>` in Sphinx.
+
+.. code:: rst
+
+   :pypi:`rst-multi-refs` provides custom roles to refer for packages of PyPI.
+
+This rendered it on HTML.
+
+  :pypi:`rst-multi-refs` provides custom roles to refer for packages of PyPI.
+
 Contents
 ========
 
 .. toctree::
    :maxdepth: 1
 
+   usage
    changelogs
    api
 

doc/usage.rst

@@ -0,0 +1,47 @@
+=====
+Usage
+=====
+
+Installation
+============
+
+Install library into your documentation project from PyPI.
+
+.. code:: console
+
+   pip install rst-multi-refs
+
+Integrate Sphinx document
+-------------------------
+
+Add bundled extension into your ``conf.py`` of document.
+
+.. code-block:: python
+   :caption: conf.py
+
+   extensions = [
+       "rst_multi_refs.sphinx",
+   ]
+
+Write a document
+================
+
+You can write text with custom roles in integrated document.
+
+.. tabs::
+
+   .. tab:: reST
+
+      .. code:: rst
+
+         :pypi:`rst-multi-refs` provides custom roles to refer for packages of PyPI.
+
+   .. tab:: MyST
+
+      .. code:: md
+
+         {pypi}`rst-multi-refs` provides custom roles to refer for packages of PyPI.
+
+This source is rendered like ths on HTML.
+
+  :pypi:`rst-multi-refs` provides custom roles to refer for packages of PyPI.

pyproject.toml

@@ -54,6 +54,7 @@ dev-dependencies = [
     "pytest~=8.0.1",
     "sphinx~=7.2.0",
     "sphinx-autobuild~=2024.2.4",
+    "sphinx-tabs~=3.4.5",
 ]
 
 [tool.rye.scripts]

requirements-dev.lock

@@ -23,6 +23,7 @@ colorama==0.4.6
 docutils==0.20.1
     # via rst-multi-refs
     # via sphinx
+    # via sphinx-tabs
 furo==2024.1.29
 idna==3.6
     # via requests
@@ -44,6 +45,7 @@ pluggy==1.4.0
 pygments==2.17.2
     # via furo
     # via sphinx
+    # via sphinx-tabs
 pytest==8.0.1
 requests==2.31.0
     # via sphinx
@@ -58,9 +60,11 @@ sphinx==7.2.6
     # via rst-multi-refs
     # via sphinx-autobuild
     # via sphinx-basic-ng
+    # via sphinx-tabs
 sphinx-autobuild==2024.2.4
 sphinx-basic-ng==1.0.0b2
     # via furo
+sphinx-tabs==3.4.5
 sphinxcontrib-applehelp==1.0.8
     # via sphinx
 sphinxcontrib-devhelp==1.0.6