A well-structured documentation homepage serves as the gateway to your product documentation. So, it must be easy to navigate and enable discoverability of your content. In this blog post, I provide a template that you can customize to create a documentation page. This template relies heavily on the elements from the sphinx-design extension, specifically cards, tabs, and grids. Sphinx-design is a Sphinx extension that lets you create beautiful web components. For more information about Sphinx-design, see their official documentation.
Preqrequisites
- You must install sphinx-design.
- Add sphinx-design to your conf.py
Restructured Text Template for a Documentation Homepage
Following is the source for our company’s documentation homepage. In future blogposts, I will provide/design homepages for various popular documentation sites such as stipe, mongodb.
.. your_project_name documentation master file, created by
sphinx-quickstart on Wed Oct 13 20:54:11 2021.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Your Project Documentation Home
==========================================
Explore our guides and examples to integrate Your Project across various solutions.
.. grid:: 2
.. grid-item-card:: Your Project for Solution 1
:link: https://yourproject.com/solution1
Brief description of Solution 1 and how Your Project integrates with it.
.. grid-item-card:: Your Project for Solution 2
:link: https://yourproject.com/solution2
Brief description of Solution 2 and how Your Project integrates with it.
Browse Documentation by Product
===============================
Explore installation, configuration, and API reference documentation categorized by Your Project products.
Product 1
---------
.. tab-set::
.. tab-item:: Product 1 Section 1
* `Section 1 Overview <link_to_section1_overview>`__
* `Section 1 Installation Guide <link_to_section1_installation>`__
* `Section 1 Configuration Reference <link_to_section1_config>`__
.. tab-item:: Product 1 Section 2
* `Section 2 Overview <link_to_section2_overview>`__
* `Section 2 Installation Guide <link_to_section2_installation>`__
* `Section 2 Configuration Reference <link_to_section2_config>`__
Product 2
---------
.. tab-set::
.. tab-item:: Product 2 Section 1
* `Section 1 Overview <link_to_section1_overview>`__
* `Section 1 Installation Guide <link_to_section1_installation>`__
* `Section 1 Configuration Reference <link_to_section1_config>`__
.. tab-item:: Product 2 Section 2
* `Section 2 Overview <link_to_section2_overview>`__
* `Section 2 Installation Guide <link_to_section2_installation>`__
* `Section 2 Configuration Reference <link_to_section2_config>`__