Merge pull request #347 from fusion-energy/imporved-docs

Imporved docs
fusion-energy · Oct 12, 2024 · 25191c0 · 25191c0
2 parents e29dd7c + f51578b
commit 25191c0
Show file tree

Hide file tree

Showing 13 changed files with 153 additions and 16 deletions.
diff --git a/docs/_static/api.svg b/docs/_static/api.svg
diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico
diff --git a/docs/_static/getting_started.svg b/docs/_static/getting_started.svg
diff --git a/docs/_static/paramak.css b/docs/_static/paramak.css
@@ -0,0 +1,13 @@
+.sd-card .sd-card-img-top {
+    height: 60px;
+    width: 60px;
+    margin-left: auto;
+    margin-right: auto;
+    margin-top: 10px;
+}
+
+/* Main index page overview images */
+
+html[data-theme=dark] .sd-card img[src*='.svg'] {
+filter: invert(0.82) brightness(0.8) contrast(1.2);
+}
diff --git a/docs/_static/user_guide.svg b/docs/_static/user_guide.svg
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,7 +14,7 @@
 
 
 project = "Paramak"
-copyright = "2024, J. Shimwell"
+copyright = "2024, Fusion Energy"
 author = "J. Shimwell"
 
 import paramak
@@ -34,6 +34,7 @@
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
     "sphinxcadquery.sphinxcadquery",
+    "sphinx_design",
 ]
 
 templates_path = ["_templates"]
@@ -45,7 +46,7 @@
 
 html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
-
+html_css_files = ["paramak.css"]
 
 # TODO add logo
 # html_favicon = "favicon.ico"
@@ -61,10 +62,20 @@
     version_match = version
 
 html_theme_options = {
+    # "primary_sidebar_end": ["sidebar-nav-bs"],
     "github_url": "https://github.com/fusion-energy/paramak",
     "switcher": {
         "json_url": "https://raw.githubusercontent.com/fusion-energy/paramak/main/docs/version_switcher.json",
         "version_match": version_match,
     },
     "navbar_start": ["version-switcher", "navbar-icon-links"],
+    "show_nav_level": 3,
+    "collapse_navigation": True,
+    "show_version_warning_banner": True,
+}
+html_sidebars = {
+    "**": ["sidebar-nav-bs"]
 }
+
+html_favicon = '_static/favicon.ico'
+master_doc = "index"
diff --git a/docs/usage.rst → docs/examples.rst b/docs/usage.rst → docs/examples.rst
@@ -1,5 +1,5 @@
-Usage
-=====
+Examples
+========
 
 There are two main reactors to choose from:
 
@@ -25,7 +25,7 @@ These examples show how to make various reactors with different options.
 .. toctree::
    :maxdepth: 3
 
-   usage_vis
-   usage_tokamak
-   usage_spherical_tokamak
+   examples_vis
+   examples_tokamak
+   examples_spherical_tokamak
 
diff --git a/docs/usage_spherical_tokamak.rst → docs/examples_spherical_tokamak.rst b/docs/usage_spherical_tokamak.rst → docs/examples_spherical_tokamak.rst
diff --git a/docs/usage_tokamak.rst → docs/examples_tokamak.rst b/docs/usage_tokamak.rst → docs/examples_tokamak.rst
diff --git a/docs/usage_vis.rst → docs/examples_vis.rst b/docs/usage_vis.rst → docs/examples_vis.rst
diff --git a/docs/index.rst b/docs/index.rst
@@ -2,18 +2,70 @@
 Paramak documentation
 =====================
 
+
+
 **Version**: |version|
 
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+   :hidden:
+
+   install
+   examples
+   python_api
+
 Parameter driven CAD creation for fusion reactors.
 
 Paramak provides parameter driven creation of Tokamak and Spherical Tokamak CAD models as well as DAGMC compatible neutronics models.
 
 The style of reaction, sizes of components, plasma shape and number of radial or vertical layers can be specified,  
 
 
-.. toctree::
-   :maxdepth: 3
 
-   install
-   usage
-   python_api
+.. grid:: 12 12 3 3
+    :gutter: 2
+
+    .. grid-item-card::
+        :img-top: _static/getting_started.svg
+        :text-align: center
+
+        Installation
+        ^^^
+
+        .. button-ref:: install
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the installation guide
+
+    .. grid-item-card::
+        :img-top: _static/user_guide.svg
+        :text-align: center
+
+        Examples
+        ^^^
+
+        .. button-ref:: examples
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the examples
+
+    .. grid-item-card::
+        :img-top: _static/api.svg
+        :text-align: center
+
+        API reference
+        ^^^
+
+        .. button-ref:: python_api
+            :expand:
+            :color: secondary
+            :click-parent:
+
+            To the reference guide
+
diff --git a/docs/python_api.rst b/docs/python_api.rst
@@ -8,11 +8,8 @@ Assemblies
 ----------
 
 .. autofunction:: tokamak
-
 .. autofunction:: tokamak_from_plasma
-
 .. autofunction:: spherical_tokamak
-
 .. autofunction:: spherical_tokamak_from_plasma
 
 Workplanes

diff --git a/pyproject.toml b/pyproject.toml
@@ -46,7 +46,8 @@ docs = [
     "sphinx",
     "pydata-sphinx-theme",
     "cadquery",
-    "ipython"
+    "ipython",
+    "sphinx_design"
 ]
 
 [tool.black]