✨ NEW: Add test_sd_hide_root_title config option (#13)

Author: chrisjsewell

docs/badges_buttons.md

@@ -131,6 +131,9 @@ color
 outline
 : Outline color variant
 
+align
+: Align the button on the page; left, right, center or justify
+
 expand
 : Expand to fit parent width
 

docs/conf.py

@@ -37,7 +37,7 @@
         "use_issues_button": True,
         "repository_branch": "main",
         "path_to_docs": "docs",
-        "home_page_in_toc": True,
+        "home_page_in_toc": False,
         "logo_only": True,
     }
 if html_theme == "furo":
@@ -65,3 +65,5 @@
     "Nam sed arcu dignissim, ultrices quam sit amet, commodo ipsum. "
     "Etiam quis nunc at ligula tincidunt eleifend."
 }
+
+sd_hide_root_title = True

docs/css_classes.md

@@ -34,6 +34,13 @@ Classes are available for styling and alignment:
   - `sd-text-left`
   - `sd-text-right`
   - `sd-text-center`
+- Size (size decreases from 1 to 6):
+  - `sd-fs-1`
+  - `sd-fs-2`
+  - `sd-fs-3`
+  - `sd-fs-4`
+  - `sd-fs-5`
+  - `sd-fs-6`
 - Weight:
   - `sd-font-weight-light`
   - `sd-font-weight-lighter`

docs/get_started.md

@@ -0,0 +1,44 @@
+# Getting Started
+
+```{article-info}
+:avatar: images/ebp-logo.png
+:avatar-link: https://executablebooks.org
+:author: "[Chris Sewell](https://github.com/chrisjsewell)"
+:date: "{sub-ref}`today`"
+:read-time: "1 min read"
+:class-avatar: sd-animate-grow50-rot20
+```
+
+## Usage
+
+Simply pip install `sphinx-design` and add the extension to your `conf.py`:
+
+```python
+extensions = ["sphinx_design"]
+```
+
+For using with [MyST Parser](https://github.com/executablebooks/myst-parser), for Markdown documentation, it is recommended to use the `colon_fence` syntax extension:
+
+```python
+extensions = ["myst_parser", "sphinx_design"]
+myst_enable_extensions = ["colon_fence"]
+```
+
+## Configuration
+
+To hide the the title header on the landing page (i.e. root document), add the following to your `conf.py`:
+
+```python
+sd_hide_root_title = True
+```
+
+## Supported browsers
+
+- Chrome >= 60
+- Firefox >= 60
+- Firefox ESR
+- iOS >= 12
+- Safari >= 12
+- Explorer >= 12
+
+(Mirrors: <https://github.com/twbs/bootstrap/blob/v5.0.2/.browserslistrc>)

docs/index.md

@@ -1,15 +1,34 @@
 # sphinx-design
 
-```{article-info}
-:avatar: images/ebp-logo.png
-:avatar-link: https://executablebooks.org
-:author: "[Chris Sewell](https://github.com/chrisjsewell)"
-:date: "{sub-ref}`today`"
-:read-time: "5 min read"
-:class-avatar: sd-animate-grow50-rot20
+::::{grid}
+:reverse:
+:gutter: 2 1 1 1
+:margin: 4 1 1 1
+
+:::{grid-item}
+:columns: 12 4 4 4
+
+```{image} ./_static/logo_square.svg
+:width: 200px
+:class: sd-m-auto sd-animate-grow50-rot20
 ```
+:::
+
+:::{grid-item}
+:columns: 12 8 8 8
+:class: sd-align-items-center sd-fs-3
+
+A sphinx extension for designing beautiful, screen-size responsive web-components.
+:::
+::::
+
+```{button-ref} get_started
+:color: primary
+:align: center
+:class: sd-fs-5
 
-A sphinx extension for designing beautiful, screen-size responsive web components.
+Get Started
+```
 
 Conflict free CSS
 : All CSS classes are prefixed, to avoid conflicts with other frameworks.
@@ -23,6 +42,12 @@ Configurable
 Supports non-HTML output formats
 : Components degrade gracefully for non-HTML formats.
 
+```{toctree}
+:hidden:
+
+get_started
+```
+
 ```{toctree}
 :caption: Components
 :hidden:
@@ -103,29 +128,3 @@ Change the default colors and other CSS.
 ::::
 
 Created with inspiration from [Bootstrap](https://getbootstrap.com/) (v5), [Material Design](https://material.io) and [Material-UI](https://material-ui.com/) design frameworks.
-
-## Usage
-
-Simply pip install `sphinx-design` and add the extension to your `conf.py`:
-
-```python
-extensions = ["sphinx_design"]
-```
-
-For using with [MyST Parser](https://github.com/executablebooks/myst-parser), for Markdown documentation, it is recommended to use the `colon_fence` syntax extension:
-
-```python
-extensions = ["myst_parser", "sphinx_design"]
-myst_enable_extensions = ["colon_fence"]
-```
-
-## Supported browsers
-
-- Chrome >= 60
-- Firefox >= 60
-- Firefox ESR
-- iOS >= 12
-- Safari >= 12
-- Explorer >= 12
-
-(Mirrors: <https://github.com/twbs/bootstrap/blob/v5.0.2/.browserslistrc>)

sphinx_design/badges_buttons.py

@@ -6,7 +6,7 @@
 from sphinx.application import Sphinx
 from sphinx.util.docutils import ReferenceRole, SphinxDirective, SphinxRole
 
-from sphinx_design.shared import SEMANTIC_COLORS, make_choice
+from sphinx_design.shared import SEMANTIC_COLORS, make_choice, text_align
 
 ROLE_NAME_BADGE_PREFIX = "bdg"
 ROLE_NAME_LINK_PREFIX = "bdg-link"
@@ -137,6 +137,7 @@ class _ButtonDirective(SphinxDirective):
     option_spec = {
         "color": make_choice(SEMANTIC_COLORS),
         "outline": directives.flag,
+        "align": text_align,
         # expand to fit parent width
         "expand": directives.flag,
         # make parent also clickable
@@ -188,7 +189,7 @@ def run(self) -> List[nodes.Node]:
             node = grid_container
 
         # `visit_reference` requires that a reference be inside a `TextElement` parent
-        container = nodes.paragraph()
+        container = nodes.paragraph(classes=self.options.get("align", []))
         self.set_source_info(container)
         container += node
 

sphinx_design/compiled/style.min.css

@@ -11,6 +11,7 @@
 from docutils.parsers.rst import directives
 from sphinx.application import Sphinx
 from sphinx.environment import BuildEnvironment
+from sphinx.transforms import SphinxTransform
 from sphinx.util.docutils import SphinxDirective
 
 from . import compiled as static_module
@@ -26,6 +27,7 @@
 
 def setup_extension(app: Sphinx) -> None:
     """Set up the sphinx extension."""
+    app.add_config_value("sd_hide_root_title", False, "env")
     app.connect("builder-inited", update_css_js)
     app.connect("env-updated", update_css_links)
     # we override container html visitors, to stop the default behaviour
@@ -44,6 +46,7 @@ def setup_extension(app: Sphinx) -> None:
     app.add_directive(
         "div", Div, override=True
     )  # override sphinx-panels implementation
+    app.add_transform(AddFirstTitleCss)
     setup_badges_and_buttons(app)
     setup_cards(app)
     setup_grids(app)
@@ -132,3 +135,27 @@ def run(self):
         self.add_name(node)
         self.state.nested_parse(self.content, self.content_offset, node)
         return [node]
+
+
+class AddFirstTitleCss(SphinxTransform):
+    """Add a CSS class to to the first sections title."""
+
+    default_priority = 699  # priority main
+
+    def apply(self):
+        if not self.app.config.sd_hide_root_title:
+            return
+        # from sphinx 4 master_doc is deprecated for root_doc
+        try:
+            if self.env.docname != self.config.root_doc:
+                return
+        except Exception:
+            if self.env.docname != self.config.master_doc:
+                return
+        for section in self.document.traverse(nodes.section):
+            if isinstance(section.children[0], nodes.title):
+                if "classes" in section.children[0]:
+                    section.children[0]["classes"].append("sd-d-none")
+                else:
+                    section.children[0]["classes"] = ["sd-d-none"]
+            break

sphinx_design/extension.py

@@ -68,3 +68,19 @@
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+
+$font-sizes: (
+  1: calc(1.375rem + 1.5vw),
+  2: calc(1.325rem + 0.9vw),
+  3: calc(1.3rem + 0.6vw),
+  4: calc(1.275rem + 0.3vw),
+  5: 1.25rem,
+  6: 1rem
+);
+
+@each $id, $value in $font-sizes {
+  .sd-fs-#{$id}, .sd-fs-#{$id} > p {
+    font-size: $value !important;
+    line-height: unset !important;
+  }
+}

style/_text.scss

@@ -103,3 +103,20 @@ def test_snippets_myst_post(
         extension=".xml",
         encoding="utf8",
     )
+
+
+def test_sd_hide_root_title(
+    sphinx_builder: Callable[..., SphinxBuilder], file_regression
+):
+    """Test that the root title is hidden."""
+    builder = sphinx_builder(
+        conf_kwargs={"extensions": ["sphinx_design"], "sd_hide_root_title": True}
+    )
+    content = "Heading\n-------" + "\n\ncontent"
+    builder.src_path.joinpath("index.rst").write_text(content, encoding="utf8")
+    builder.build()
+    file_regression.check(
+        builder.get_doctree("index", post_transforms=False).pformat(),
+        extension=".xml",
+        encoding="utf8",
+    )