diff --git a/docs/_static/api.svg b/docs/_static/api.svg new file mode 100644 index 000000000..e637525cc --- /dev/null +++ b/docs/_static/api.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/favicon.ico b/docs/_static/favicon.ico new file mode 100644 index 000000000..f8aa2c31f Binary files /dev/null and b/docs/_static/favicon.ico differ diff --git a/docs/_static/getting_started.svg b/docs/_static/getting_started.svg new file mode 100644 index 000000000..04db7e615 --- /dev/null +++ b/docs/_static/getting_started.svg @@ -0,0 +1,31 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/paramak.css b/docs/_static/paramak.css new file mode 100644 index 000000000..ae33233cd --- /dev/null +++ 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 new file mode 100644 index 000000000..d61b0937d --- /dev/null +++ b/docs/_static/user_guide.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index f0877ba2e..a9956bd14 100644 --- 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 b/docs/examples.rst similarity index 90% rename from docs/usage.rst rename to docs/examples.rst index 37975f2c6..efef2f858 100644 --- a/docs/usage.rst +++ b/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 b/docs/examples_spherical_tokamak.rst similarity index 100% rename from docs/usage_spherical_tokamak.rst rename to docs/examples_spherical_tokamak.rst diff --git a/docs/usage_tokamak.rst b/docs/examples_tokamak.rst similarity index 100% rename from docs/usage_tokamak.rst rename to docs/examples_tokamak.rst diff --git a/docs/usage_vis.rst b/docs/examples_vis.rst similarity index 100% rename from docs/usage_vis.rst rename to docs/examples_vis.rst diff --git a/docs/index.rst b/docs/index.rst index f8fa606e5..e624c9318 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,8 +2,20 @@ 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. @@ -11,9 +23,49 @@ Paramak provides parameter driven creation of Tokamak and Spherical Tokamak CAD 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 index d4504f06d..33703d0b4 100644 --- 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 index 09e2a443d..3525d858e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -46,7 +46,8 @@ docs = [ "sphinx", "pydata-sphinx-theme", "cadquery", - "ipython" + "ipython", + "sphinx_design" ] [tool.black]