Merge pull request #143 from callowayproject/doc-conversion

Updated docs and styles

.github/workflows/docs-final.yml

@@ -0,0 +1,30 @@
+name: Deploy final documentation
+
+on:
+  push:
+    branches: [ "master" ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          git pull --all
+          python -m pip install ".[docs]"
+
+      - name: Build and deploy documentation
+        run: |
+          mkdocs gh-deploy --strict -v

.github/workflows/docs-preview.yml

@@ -0,0 +1,38 @@
+name: Deploy PR previews
+
+on:
+  pull_request:
+    types:
+      - opened
+      - reopened
+      - synchronize
+      - closed
+
+concurrency: preview-${{ github.ref }}
+
+jobs:
+  deploy-preview:
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install ".[docs]"
+
+      - name: Build documentation
+        run: |
+          mkdocs build --strict -v
+
+      - name: Deploy preview
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: ./site/

bumpversion/config/__init__.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Union
+from typing import TYPE_CHECKING, Any, Union
 
 from bumpversion.config.files import read_config_file
 from bumpversion.config.models import Config
@@ -37,7 +37,7 @@
 }
 
 
-def get_configuration(config_file: Union[str, Path, None] = None, **overrides) -> Config:
+def get_configuration(config_file: Union[str, Path, None] = None, **overrides: Any) -> Config:
     """
     Return the configuration based on any configuration files and overrides.
 

docsrc/CHANGELOG.md

@@ -0,0 +1,6 @@
+---
+comments: true
+title: "Changelog"
+---
+
+{% include-markdown "../CHANGELOG.md" %}

docsrc/contributing.md → docsrc/CONTRIBUTING.md

@@ -1 +1,6 @@
+---
+comments: true
+title: "Contributing"
+---
+
 {% include-markdown "../CONTRIBUTING.md" rewrite-relative-urls=false %}

docsrc/_static/css/custom.css

@@ -1,70 +1,12 @@
-.class .sig-prename.descclassname {
-  display: none;
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
 }
 
-.subheading {
-  line-height: 1.25;
-  margin-bottom: 0;
-  color: #646776;
-}
-
-.subheading + section > h1 {
-  margin-top: 0;
-}
-
-.field-list p {
-  margin: 0;
-}
-
-.field-list > dl {
-  --gap: 1rem;
-  --line-offset: calc(var(--gap) / 2);
-  --line-thickness: 1px;
-  --line-color: #e0e0e0;
-
-  display: grid;
-  grid-template-columns: fit-content(30%) auto;
-  grid-gap: var(--gap);
-  margin-bottom: 1rem;
-  overflow: hidden;
-}
-
-.field-list > dl > dt {
-  text-align: right;
-  font-weight: bold;
-  word-break: break-word;
-  position: relative;
-}
-
-[dir=ltr] .field-list > dl > dd {
-  margin-top: 0;
-  margin-left: 0;
-  margin-bottom: 0;
-  position: relative;
-}
-
-/* Pseudo Element Shared Styling */
-.field-list > dl > dt::before,
-.field-list > dl > dt::after,
-.field-list > dl > dd::before,
-.field-list > dl > dd::after {
-   content: '';
-   position: absolute;
-   background-color: var(--line-color);
-   z-index: 1;
-}
-
-/* Row Borders */
-.field-list > dl > dt::after,
-.field-list > dl > dd::after {
-  inline-size: 100vw;
-  block-size: var(--line-thickness);
-  inset-inline-start: 0;
-  inset-block-start: calc(var(--line-offset) * -1);
-}
-
-
-figure {
-  padding-bottom: .75rem;
-  padding-top: .5rem;
+/* Normal size fonts on parameter tables */
+.md-typeset div.doc-contents table {
+  font-size: 1em;
+  width: 100%;
+  display: table;
 }

docsrc/_static/css/field-list.css

@@ -0,0 +1,61 @@
+dl.field-list .doc-param-default, dl.doc-field-list .doc-param-default {
+  float: none;
+}
+
+dd.doc-field-def > p:last-child {
+  padding-bottom: 0;
+  margin-bottom: 0;
+}
+
+dl.field-list, dl.doc-field-list {
+  display: flex;
+  flex-flow: row wrap;
+  padding-left: 10px;
+}
+
+dl.field-list > dt, dl.doc-field-list > dt {
+  flex-basis: 20%;
+  font-weight: bold;
+  word-break: break-word;
+  padding: 10px 0;
+  border-bottom: 1px solid #e5e5e5;
+}
+
+dl.field-list > dt:after {
+  content: ":";
+}
+
+dl.field-list > dd.doc-field-def, dl.doc-field-list > dd.doc-field-def {
+  flex-basis: 70%;
+  flex-grow: 1;
+  margin: 0;
+  padding: 10px 0 10px 10px;
+  border-bottom: 1px solid #e5e5e5;
+}
+
+dl {
+  margin-bottom: 15px;
+}
+
+dd > :first-child {
+  margin-top: 0;
+}
+
+dd ul, dd table {
+  margin-bottom: 10px;
+}
+
+dd {
+  margin-top: 3px;
+  margin-bottom: 10px;
+  margin-left: 30px;
+}
+
+dl > dd:last-child,
+dl > dd:last-child > :last-child {
+  margin-bottom: 0;
+}
+
+dt:target, span.highlighted {
+  background-color: #fbe54e;
+}

docsrc/_static/css/mkdocstrings.css

@@ -25,3 +25,15 @@ a.external:hover::after,
 a.autorefs-external:hover::after {
   background-color: var(--md-accent-fg-color);
 }
+
+.doc-param-key, .doc-field-term, .doc-section-head {
+  font-weight: bold;
+}
+
+.doc.doc-heading {
+  text-transform: none;
+}
+
+h5.doc-heading, h6.doc-heading {
+  font-size: 1em;
+}

docsrc/index.md

@@ -1,3 +1,8 @@
+---
+comments: true
+title: Bump My Version
+---
+
 # Bump My Version
 
 {% 

docsrc/reference/index.md

@@ -6,4 +6,4 @@
 - [Formatting context](formatting-context.md)
 - [Version parts](version-parts.md)
 - [Search and replace configuration](search-and-replace-config.md)
-- [API](api/bumpversion.md)
+- [API](api/bumpversion/index.md)

mkdocs.yml

@@ -23,6 +23,7 @@ theme:
   palette:
     - media: "(prefers-color-scheme: light)"
       scheme: default
+      primary: blue grey
       toggle:
         icon: material/toggle-switch-off-outline
         name: Switch to dark mode
@@ -31,13 +32,13 @@ theme:
       toggle:
         icon: material/toggle-switch
         name: Switch to light mode
-use_directory_urls: false
+use_directory_urls: true
 markdown_extensions:
   - abbr
   - admonition
   - attr_list
-  - def_list
   - customblocks
+  - def_list
   - footnotes
   - md_in_html
   - mdx_truly_sane_lists
@@ -48,12 +49,17 @@ markdown_extensions:
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight
   - pymdownx.snippets
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_div_format
   - pymdownx.tabbed:
       alternate_style: true
       slugify: !!python/object/apply:pymdownx.slugs.slugify
         kwds:
           case: lower
+  - smarty
   - toc:
       permalink: true
       toc_depth: 3
@@ -64,6 +70,8 @@ plugins:
   - git-revision-date-localized
   - git-authors:
       show_email_address: false
+      exclude:
+        - reference/api/*
   - include-markdown
   - drawio
   - literate-nav:
@@ -92,6 +100,7 @@ plugins:
             merge_init_into_class: true
             separate_signature: true
             show_docstring_parameters: true
+            show_root_toc_entry: true
             show_signature_annotations: true
             show_source: false
             show_symbol_type_heading: true
@@ -105,6 +114,7 @@ extra_css:
   - _static/css/custom.css
   - _static/css/mkdocstrings.css
   - _static/css/cards.css
+  - _static/css/field-list.css
 
 #nav:
 #  - General: "general/"