Create new CLI command "nbdev mkdocs readme" (#206)

* WIP * Add new command for generating readme * Polish tests * Polish tests * Assign default value if the docs_versioning variable is not set in the settings.ini file --------- Co-authored-by: Sean Bartik <[email protected]>
airtai · Jul 7, 2023 · 49f7a31 · 49f7a31
1 parent cc24eda
commit 49f7a31
Show file tree

Hide file tree

Showing 13 changed files with 675 additions and 99 deletions.
diff --git a/.secrets.baseline b/.secrets.baseline
@@ -116,9 +116,9 @@
       {
         "type": "Base64 High Entropy String",
         "filename": "nbs/CLI.ipynb",
-        "hashed_secret": "0c3a05f3131ff4ed8e23b97f6bb62e7c3dc932f2",
+        "hashed_secret": "0e0ee03507fa574824f912c4fa0576dd4e3854b2",
         "is_verified": false,
-        "line_number": 351,
+        "line_number": 355,
         "is_secret": false
       }
     ],
@@ -133,5 +133,5 @@
       }
     ]
   },
-  "generated_at": "2023-06-28T12:54:26Z"
+  "generated_at": "2023-07-07T06:18:05Z"
 }
diff --git a/README.md b/README.md
@@ -1,5 +1,4 @@
-Material for nbdev
-================
+# Material for nbdev
 
 <!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->
 
@@ -186,7 +185,7 @@ the required libraries.
 
 For detailed installation instructions and configuration options, please
 see the
-<a href="https://nbdev-mkdocs.airt.ai/guides/Basic_User_Guide/">User
+<a href="https://nbdev-mkdocs.airt.ai/latest/guides/Basic_User_Guide/">User
 Guide</a>.
 
 ### Install
@@ -221,17 +220,21 @@ nbdev_mkdocs --help
     ╭─ Commands ───────────────────────────────────────────────────────────────────╮
     │ delete-pre-release-docs  Deletes deployed pre-release documentation          │
     │                          versions.                                           │
-    │ docs                     Prepares files in **mkdocs/docs** and then runs     │
-    │                          **mkdocs build** command on them                    │
+    │ docs                     Prepares files in 'mkdocs/docs' and then runs       │
+    │                          'mkdocs build' command on them.                     │
     │ docstring                Command for adding docstrings to classes and        │
     │                          methods that don't have one using docstring-gen     │
     │                          library.                                            │
-    │ new                      Creates files in **mkdocs** subdirectory needed for │
-    │                          other **nbdev_mkdocs** subcommands                  │
-    │ prepare                  Runs tests and prepares files in **mkdocs/docs**    │
-    │                          and then runs **mkdocs build** command on them      │
-    │ preview                  Prepares files in **mkdocs/docs** and then runs     │
-    │                          **mkdocs serve** command on them                    │
+    │ new                      Creates files in 'mkdocs' subdirectory needed for   │
+    │                          other 'nbdev_mkdocs' subcommands.                   │
+    │ prepare                  Runs tests and prepares files in 'mkdocs/docs' and  │
+    │                          then runs 'mkdocs build' command on them.           │
+    │ preview                  Prepares files in 'mkdocs/docs' and then runs       │
+    │                          'mkdocs serve' command on them.                     │
+    │ readme                   Updates the README.md file from the 'readme_nb'     │
+    │                          notebook. Unless explicitly changed in the          │
+    │                          settings.ini file, the 'readme_nb' points to the    │
+    │                          'index.ipynb' notebook in the 'nbs_path' directory. │
     │ social-image             Command for generating a custom social share image. │
     ╰──────────────────────────────────────────────────────────────────────────────╯
 
@@ -268,14 +271,29 @@ nbdev_mkdocs preview
 
 #### Prepare changes
 
-We recommend running the `nbdev_mkdocs prepare` command in the terminal
-before committing to Git, which exports the library, tests and cleans
-notebooks, and generates the README file if necessary.
+To prepare your changes for Git push, we recommend executing the
+following commands:
+
+First, run the `nbdev_mkdocs prepare` command in the terminal. This
+command exports the library, runs tests, and cleans the notebooks.
 
 ``` shell
 nbdev_mkdocs prepare
 ```
 
+Then, run the `nbdev_mkdocs readme` command to update the README.md file
+from the ‘readme_nb’ notebook. By default, ‘readme_nb’ points to
+‘index.ipynb’ notebook in the ‘nbs_path’ unless modified in the
+settings.ini file.
+
+This command does everything the ‘nbdev_readme’ command does, plus it
+generates symbol references that are compatible with ‘Material for
+nbdev’.
+
+``` shell
+nbdev_mkdocs readme
+```
+
 Finally, double-check your settings.ini file to ensure that it has all
 of the correct information. Then commit and push your additions to
 GitHub:

diff --git a/nbdev_mkdocs/__init__.py b/nbdev_mkdocs/__init__.py
@@ -1 +1 @@
-__version__ = "0.6.0"
+__version__ = "0.7.0rc0"
diff --git a/nbdev_mkdocs/_cli.py b/nbdev_mkdocs/_cli.py
@@ -1,7 +1,7 @@
 # AUTOGENERATED! DO NOT EDIT! File to edit: ../nbs/CLI.ipynb.
 
 # %% auto 0
-__all__ = ['new', 'prepare', 'preview', 'docs', 'delete_pre_release_docs']
+__all__ = ['new', 'prepare', 'preview', 'docs', 'readme', 'delete_pre_release_docs']
 
 # %% ../nbs/CLI.ipynb 1
 import subprocess  # nosec: B404
@@ -21,7 +21,7 @@
 
 
 @_app.command(
-    help="Creates files in **mkdocs** subdirectory needed for other **nbdev_mkdocs** subcommands",
+    help="Creates files in 'mkdocs' subdirectory needed for other 'nbdev_mkdocs' subcommands.",
 )
 def new(root_path: str = typer.Option(".", help="")) -> None:
     """CLI command for creating files for nbdev_mkdocs command"""
@@ -33,10 +33,10 @@ def new(root_path: str = typer.Option(".", help="")) -> None:
 
 
 @_app.command(
-    help="Runs tests and prepares files in **mkdocs/docs** and then runs **mkdocs build** command on them ",
+    help="Runs tests and prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on them.",
 )
 def prepare(root_path: str = typer.Option(".", help="")) -> None:
-    """CLI command for running tests and creating files for nbdev_mkdocs command"""
+    """CLI command for running tests and creating files for nbdev_mkdocs command."""
     try:
         nbdev_mkdocs.mkdocs.prepare(root_path=root_path)
     except Exception as e:
@@ -45,7 +45,7 @@ def prepare(root_path: str = typer.Option(".", help="")) -> None:
 
 
 @_app.command(
-    help="Prepares files in **mkdocs/docs** and then runs **mkdocs serve** command on them ",
+    help="Prepares files in 'mkdocs/docs' and then runs 'mkdocs serve' command on them.",
 )
 def preview(
     root_path: str = typer.Option(
@@ -72,7 +72,7 @@ def preview(
 
 
 @_app.command(
-    help="Prepares files in **mkdocs/docs** and then runs **mkdocs build** command on them ",
+    help="Prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on them.",
 )
 def docs(root_path: str = typer.Option(".", help="Project's root path.")) -> None:
     """CLI command for creating files for nbdev_mkdocs command"""
@@ -84,14 +84,29 @@ def docs(root_path: str = typer.Option(".", help="Project's root path.")) -> Non
         typer.secho(f"Unexpected internal error: {e}", err=True, fg=typer.colors.RED)
         raise typer.Exit(1)
 
+
+@_app.command(
+    help="Updates the README.md file from the 'readme_nb' notebook. \
+Unless explicitly changed in the settings.ini file, the 'readme_nb' points to the 'index.ipynb' notebook in the 'nbs_path' directory.",
+)
+def readme() -> None:
+    """CLI command for updating the README.md file from the readme_nb notebook."""
+    try:
+        from nbdev_mkdocs._components.cli_docs_generator import update_readme
+
+        update_readme()
+    except Exception as e:
+        typer.secho(f"Unexpected internal error: {e}", err=True, fg=typer.colors.RED)
+        raise typer.Exit(1)
+
 # %% ../nbs/CLI.ipynb 5
 def _create_generate_social_img_sub_cmd(_app: typer.Typer = _app) -> None:
     """Create generate social image sub command"""
     _generate_social_img_app = typer.Typer(
         help="Command for generating a custom social share image."
     )
 
-    @_generate_social_img_app.command(help="Generate a custom social share image")
+    @_generate_social_img_app.command(help="Generate a custom social share image.")
     def generate(
         root_path: str = typer.Option(".", help="Project's root path."),
         generator: nbdev_mkdocs.social_image_generator._IMG_Generator = typer.Option(

diff --git a/nbdev_mkdocs/_components/__init__.py b/nbdev_mkdocs/_components/__init__.py
diff --git a/nbdev_mkdocs/_components/cli_docs_generator.py b/nbdev_mkdocs/_components/cli_docs_generator.py
@@ -0,0 +1,35 @@
+# AUTOGENERATED! DO NOT EDIT! File to edit: ../../nbs/CLI_Docs_Generator.ipynb.
+
+# %% auto 0
+__all__ = ['update_readme']
+
+# %% ../../nbs/CLI_Docs_Generator.ipynb 1
+from typing import *
+
+from nbdev.quarto import nbdev_readme
+from nbdev.config import get_config
+from nbdev.doclinks import NbdevLookup
+
+from .._helpers.doc_links_utils import fix_sym_links
+
+# %% ../../nbs/CLI_Docs_Generator.ipynb 5
+def update_readme() -> None:
+    """Update the readme file and fix the symbol links"""
+    cfg = get_config()
+    readme_path = cfg.config_path / "README.md"
+    nbdev_readme.__wrapped__()
+
+    with open(readme_path, "r", encoding="utf-8") as f:
+        contents = f.read()
+
+    contents = fix_sym_links(
+        s=contents,
+        nbdev_lookup=NbdevLookup(incl_libs=cfg.lib_name.replace("_", "-")),
+        docs_versioning=cfg.get("docs_versioning", ""),
+        lib_version=cfg.version,
+        use_relative_doc_links=False,
+        use_latest_doc_version=True,
+    )
+
+    with open(readme_path, "w", encoding="utf-8") as f:
+        f.write(contents)
diff --git a/nbdev_mkdocs/_helpers/doc_links_utils.py b/nbdev_mkdocs/_helpers/doc_links_utils.py
@@ -106,13 +106,19 @@ def _get_current_docs_version(docs_versioning: str, lib_version: str) -> str:
     )
 
 # %% ../../nbs/Doc_Links_Utils.ipynb 23
-def _append_doc_version(fixed_part: str, docs_versioning: str, lib_version: str) -> str:
+def _append_doc_version(
+    fixed_part: str,
+    docs_versioning: str,
+    lib_version: str,
+    use_latest_doc_version: bool,
+) -> str:
     """Append the current version of the documentation to a URL.
 
     Args:
         fixed_part: The fixed part of the URL.
         docs_versioning: The value set for docs_versioning flag in settings.ini file.
         lib_version: The version of the library.
+        use_latest_doc_version: If set to True, the latest version of the docs will be appended to the url.
 
     Returns:
         The URL with the documentation version appended.
@@ -121,13 +127,15 @@ def _append_doc_version(fixed_part: str, docs_versioning: str, lib_version: str)
 
         The above docstring is autogenerated by docstring-gen library (https://docstring-gen.airt.ai)
     """
-    return (
-        f"{fixed_part}/{_get_current_docs_version(docs_versioning, lib_version)}"
-        if docs_versioning != "" and docs_versioning != "None"
-        else fixed_part
-    )
-
-# %% ../../nbs/Doc_Links_Utils.ipynb 28
+    if docs_versioning != "" and docs_versioning != "None":
+        return (
+            f"{fixed_part}/latest"
+            if use_latest_doc_version
+            else f"{fixed_part}/{_get_current_docs_version(docs_versioning, lib_version)}"
+        )
+    return fixed_part
+
+# %% ../../nbs/Doc_Links_Utils.ipynb 30
 def _get_relative_sym_path(o: Any) -> str:
     """Get the relative path of a symbol
 
@@ -149,14 +157,15 @@ def _get_relative_sym_path(o: Any) -> str:
     )
     return "/".join((_o.__module__ + "." + _o.__qualname__).split("."))
 
-# %% ../../nbs/Doc_Links_Utils.ipynb 36
+# %% ../../nbs/Doc_Links_Utils.ipynb 38
 def _update_link(  # type: ignore
     symbol: str,
     symbol_details: Tuple[str, str, str],
     nbdev_lookup: NbdevLookup,
     docs_versioning: str,
     lib_version: str,
     use_relative_doc_links: bool,
+    use_latest_doc_version: bool,
 ) -> str:
     """Update the link of a symbol
 
@@ -168,6 +177,7 @@ def _update_link(  # type: ignore
         lib_version: The current version of the library
         use_relative_doc_links: If set to True, relative link to symbols will be add in the generated
             documentation for easier local navigation
+        use_latest_doc_version: If set to True, the latest version of the docs will be appended to the symbol link.
 
     Returns:
         The updated link
@@ -178,9 +188,8 @@ def _update_link(  # type: ignore
     """
     fixed_part = "/".join(symbol_details[0].split("/")[:4])
     fixed_part_with_docs_version = _append_doc_version(
-        fixed_part, docs_versioning, lib_version
+        fixed_part, docs_versioning, lib_version, use_latest_doc_version
     )
-
     full_symbol_path = _get_sym_path_from_nbdev_lookup(nbdev_lookup, symbol_details)
     o = _import_symbol(full_symbol_path)
     relative_sym_path = _get_relative_sym_path(o)
@@ -191,8 +200,8 @@ def _update_link(  # type: ignore
 
     return updated_link
 
-# %% ../../nbs/Doc_Links_Utils.ipynb 42
-def fix_sym_links(s: str, nbdev_lookup: NbdevLookup, docs_versioning: str, lib_version: str, use_relative_doc_links: bool) -> str:  # type: ignore
+# %% ../../nbs/Doc_Links_Utils.ipynb 45
+def fix_sym_links(s: str, nbdev_lookup: NbdevLookup, docs_versioning: str, lib_version: str, use_relative_doc_links: bool, use_latest_doc_version: bool = False) -> str:  # type: ignore
     """Fix the default sym links generated by nbdev in the given string.
 
     Args:
@@ -202,6 +211,7 @@ def fix_sym_links(s: str, nbdev_lookup: NbdevLookup, docs_versioning: str, lib_v
         lib_version: The current version of the library.
         use_relative_doc_links: If set to True, relative link to symbols will be add in the generated
             documentation for easier local navigation.
+        use_latest_doc_version: If set to True, the latest version of the docs will be appended to the symbol link.
 
     Returns:
         The string with correct links added to the symbol references.
@@ -222,6 +232,7 @@ def fix_sym_links(s: str, nbdev_lookup: NbdevLookup, docs_versioning: str, lib_v
                 docs_versioning,
                 lib_version,
                 use_relative_doc_links,
+                use_latest_doc_version,
             )
             s = s.replace(match, updated_link)
     return s
diff --git a/nbdev_mkdocs/_modidx.py b/nbdev_mkdocs/_modidx.py
@@ -5,7 +5,9 @@
                 'doc_host': 'https://airtai.github.io',
                 'git_url': 'https://github.com/airtai/nbdev-mkdocs',
                 'lib_path': 'nbdev_mkdocs'},
-  'syms': { 'nbdev_mkdocs._helpers.api_docs_helper': { 'nbdev_mkdocs._helpers.api_docs_helper._add_mkdocstring_header_config': ( 'api_docs_helper.html#_add_mkdocstring_header_config',
+  'syms': { 'nbdev_mkdocs._components.cli_docs_generator': { 'nbdev_mkdocs._components.cli_docs_generator.update_readme': ( 'cli_docs_generator.html#update_readme',
+                                                                                                                            'nbdev_mkdocs/_components/cli_docs_generator.py')},
+            'nbdev_mkdocs._helpers.api_docs_helper': { 'nbdev_mkdocs._helpers.api_docs_helper._add_mkdocstring_header_config': ( 'api_docs_helper.html#_add_mkdocstring_header_config',
                                                                                                                                  'nbdev_mkdocs/_helpers/api_docs_helper.py'),
                                                        'nbdev_mkdocs._helpers.api_docs_helper._filter_attributes_in_autodoc': ( 'api_docs_helper.html#_filter_attributes_in_autodoc',
                                                                                                                                 'nbdev_mkdocs/_helpers/api_docs_helper.py'),