diff --git a/.secrets.baseline b/.secrets.baseline
index 757f6a5e..80bf2274 100644
--- 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
index ca68084c..0054f9c1 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
-Material for nbdev
-================
+# Material for nbdev
@@ -186,7 +185,7 @@ the required libraries.
For detailed installation instructions and configuration options, please
see the
-User
+User
Guide.
### 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
index 906d362f..5f56b076 100644
--- 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
index e4604129..685f8dcc 100644
--- 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,6 +84,21 @@ 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"""
@@ -91,7 +106,7 @@ def _create_generate_social_img_sub_cmd(_app: typer.Typer = _app) -> None:
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
new file mode 100644
index 00000000..e69de29b
diff --git a/nbdev_mkdocs/_components/cli_docs_generator.py b/nbdev_mkdocs/_components/cli_docs_generator.py
new file mode 100644
index 00000000..186c5a7c
--- /dev/null
+++ 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
index cd31d162..960c575a 100644
--- 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,7 +157,7 @@ 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],
@@ -157,6 +165,7 @@ def _update_link( # type: ignore
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
index f3927999..fee7d70c 100644
--- 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'),
diff --git a/nbs/CLI.ipynb b/nbs/CLI.ipynb
index 38f7bc0d..dcec4cfa 100644
--- a/nbs/CLI.ipynb
+++ b/nbs/CLI.ipynb
@@ -15,16 +15,7 @@
"execution_count": null,
"id": "3f5a4483",
"metadata": {},
- "outputs": [
- {
- "name": "stderr",
- "output_type": "stream",
- "text": [
- "/Users/harishm/.pyenv/versions/3.10.4/lib/python3.10/site-packages/pandas/compat/__init__.py:124: UserWarning: Could not import the lzma module. Your installed Python is incomplete. Attempting to use lzma compression will result in a RuntimeError.\n",
- " warnings.warn(msg)\n"
- ]
- }
- ],
+ "outputs": [],
"source": [
"# | export\n",
"\n",
@@ -79,7 +70,7 @@
"\n",
"\n",
"@_app.command(\n",
- " help=\"Creates files in **mkdocs** subdirectory needed for other **nbdev_mkdocs** subcommands\",\n",
+ " help=\"Creates files in 'mkdocs' subdirectory needed for other 'nbdev_mkdocs' subcommands.\",\n",
")\n",
"def new(root_path: str = typer.Option(\".\", help=\"\")) -> None:\n",
" \"\"\"CLI command for creating files for nbdev_mkdocs command\"\"\"\n",
@@ -91,10 +82,10 @@
"\n",
"\n",
"@_app.command(\n",
- " help=\"Runs tests and prepares files in **mkdocs/docs** and then runs **mkdocs build** command on them \",\n",
+ " help=\"Runs tests and prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on them.\",\n",
")\n",
"def prepare(root_path: str = typer.Option(\".\", help=\"\")) -> None:\n",
- " \"\"\"CLI command for running tests and creating files for nbdev_mkdocs command\"\"\"\n",
+ " \"\"\"CLI command for running tests and creating files for nbdev_mkdocs command.\"\"\"\n",
" try:\n",
" nbdev_mkdocs.mkdocs.prepare(root_path=root_path)\n",
" except Exception as e:\n",
@@ -103,7 +94,7 @@
"\n",
"\n",
"@_app.command(\n",
- " help=\"Prepares files in **mkdocs/docs** and then runs **mkdocs serve** command on them \",\n",
+ " help=\"Prepares files in 'mkdocs/docs' and then runs 'mkdocs serve' command on them.\",\n",
")\n",
"def preview(\n",
" root_path: str = typer.Option(\n",
@@ -130,7 +121,7 @@
"\n",
"\n",
"@_app.command(\n",
- " help=\"Prepares files in **mkdocs/docs** and then runs **mkdocs build** command on them \",\n",
+ " help=\"Prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on them.\",\n",
")\n",
"def docs(root_path: str = typer.Option(\".\", help=\"Project's root path.\")) -> None:\n",
" \"\"\"CLI command for creating files for nbdev_mkdocs command\"\"\"\n",
@@ -140,6 +131,19 @@
" )\n",
" except Exception as e:\n",
" typer.secho(f\"Unexpected internal error: {e}\", err=True, fg=typer.colors.RED)\n",
+ " raise typer.Exit(1)\n",
+ " \n",
+ "@_app.command(\n",
+ " help=\"Updates the README.md file from the 'readme_nb' notebook. \\\n",
+ "Unless explicitly changed in the settings.ini file, the 'readme_nb' points to the 'index.ipynb' notebook in the 'nbs_path' directory.\",\n",
+ ")\n",
+ "def readme() -> None:\n",
+ " \"\"\"CLI command for updating the README.md file from the readme_nb notebook.\"\"\"\n",
+ " try:\n",
+ " from nbdev_mkdocs._components.cli_docs_generator import update_readme\n",
+ " update_readme()\n",
+ " except Exception as e:\n",
+ " typer.secho(f\"Unexpected internal error: {e}\", err=True, fg=typer.colors.RED)\n",
" raise typer.Exit(1)"
]
},
@@ -159,7 +163,7 @@
" help=\"Command for generating a custom social share image.\"\n",
" )\n",
"\n",
- " @_generate_social_img_app.command(help=\"Generate a custom social share image\")\n",
+ " @_generate_social_img_app.command(help=\"Generate a custom social share image.\")\n",
" def generate(\n",
" root_path: str = typer.Option(\".\", help=\"Project's root path.\"),\n",
" generator: nbdev_mkdocs.social_image_generator._IMG_Generator = typer.Option(\n",
@@ -330,15 +334,15 @@
"name": "stdout",
"output_type": "stream",
"text": [
- "Successfully added docstrings to /private/var/folders/6n/3rjds7v52cd83wqkd565db0h0000gn/T/tmpilb8lrez/nbs/test.py\n",
+ "Successfully added docstrings to /private/var/folders/6n/3rjds7v52cd83wqkd565db0h0000gn/T/tmpk5xf8cpt/nbs/test.py\n",
"\n",
"\n",
"def sum(num1: int, num2: int) -> int:\n",
- " \"\"\"Calculate the sum of two numbers.\n",
+ " \"\"\"Calculates the sum of two numbers.\n",
"\n",
" Args:\n",
- " num1: The first number\n",
- " num2: The second number\n",
+ " num1: The first number.\n",
+ " num2: The second number.\n",
"\n",
" Returns:\n",
" The sum of num1 and num2.\n",
@@ -348,7 +352,7 @@
" \"\"\"\n",
" return num1 + num2\n",
"\n",
- "Path '/private/var/folders/6n/3rjds7v52cd83wqkd565db0h0000gn/T/tmpilb8lrez/invalid_directory_name' does not exists!\n",
+ "Path '/private/var/folders/6n/3rjds7v52cd83wqkd565db0h0000gn/T/tmpk5xf8cpt/invalid_directory_name' does not exists!\n",
"\n"
]
}
@@ -600,13 +604,16 @@
"text/html": [
"╭─ Commands ──────────────────────────────────────────────────────────────────────────────────────────────────────╮\n",
"│ delete-pre-release-docs Deletes deployed pre-release documentation versions. │\n",
- "│ docs Prepares files in **mkdocs/docs** and then runs **mkdocs build** command on them │\n",
+ "│ docs Prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on them. │\n",
"│ docstring Command for adding docstrings to classes and methods that don't have one using │\n",
"│ docstring-gen library. │\n",
- "│ new Creates files in **mkdocs** subdirectory needed for other **nbdev_mkdocs** subcommands │\n",
- "│ prepare Runs tests and prepares files in **mkdocs/docs** and then runs **mkdocs build** │\n",
- "│ command on them │\n",
- "│ preview Prepares files in **mkdocs/docs** and then runs **mkdocs serve** command on them │\n",
+ "│ new Creates files in 'mkdocs' subdirectory needed for other 'nbdev_mkdocs' subcommands. │\n",
+ "│ prepare Runs tests and prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on │\n",
+ "│ them. │\n",
+ "│ preview Prepares files in 'mkdocs/docs' and then runs 'mkdocs serve' command on them. │\n",
+ "│ readme Updates the README.md file from the 'readme_nb' notebook. Unless explicitly changed in │\n",
+ "│ the settings.ini file, the 'readme_nb' points to the 'index.ipynb' notebook in the │\n",
+ "│ 'nbs_path' directory. │\n",
"│ social-image Command for generating a custom social share image. │\n",
"╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\n",
"\n"
@@ -614,13 +621,16 @@
"text/plain": [
"\u001b[2m╭─\u001b[0m\u001b[2m Commands \u001b[0m\u001b[2m─────────────────────────────────────────────────────────────────────────────────────────────────────\u001b[0m\u001b[2m─╮\u001b[0m\n",
"\u001b[2m│\u001b[0m \u001b[1;36mdelete-pre-release-docs\u001b[0m\u001b[1;36m \u001b[0m Deletes deployed pre-release documentation versions. \u001b[2m│\u001b[0m\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mdocs \u001b[0m\u001b[1;36m \u001b[0m Prepares files in **mkdocs/docs** and then runs **mkdocs build** command on them \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mdocs \u001b[0m\u001b[1;36m \u001b[0m Prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on them. \u001b[2m│\u001b[0m\n",
"\u001b[2m│\u001b[0m \u001b[1;36mdocstring \u001b[0m\u001b[1;36m \u001b[0m Command for adding docstrings to classes and methods that don't have one using \u001b[2m│\u001b[0m\n",
"\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m docstring-gen library. \u001b[2m│\u001b[0m\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mnew \u001b[0m\u001b[1;36m \u001b[0m Creates files in **mkdocs** subdirectory needed for other **nbdev_mkdocs** subcommands \u001b[2m│\u001b[0m\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mprepare \u001b[0m\u001b[1;36m \u001b[0m Runs tests and prepares files in **mkdocs/docs** and then runs **mkdocs build** \u001b[2m│\u001b[0m\n",
- "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m command on them \u001b[2m│\u001b[0m\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mpreview \u001b[0m\u001b[1;36m \u001b[0m Prepares files in **mkdocs/docs** and then runs **mkdocs serve** command on them \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mnew \u001b[0m\u001b[1;36m \u001b[0m Creates files in 'mkdocs' subdirectory needed for other 'nbdev_mkdocs' subcommands. \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mprepare \u001b[0m\u001b[1;36m \u001b[0m Runs tests and prepares files in 'mkdocs/docs' and then runs 'mkdocs build' command on \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m them. \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mpreview \u001b[0m\u001b[1;36m \u001b[0m Prepares files in 'mkdocs/docs' and then runs 'mkdocs serve' command on them. \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mreadme \u001b[0m\u001b[1;36m \u001b[0m Updates the README.md file from the 'readme_nb' notebook. Unless explicitly changed in \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m the settings.ini file, the 'readme_nb' points to the 'index.ipynb' notebook in the \u001b[2m│\u001b[0m\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m 'nbs_path' directory. \u001b[2m│\u001b[0m\n",
"\u001b[2m│\u001b[0m \u001b[1;36msocial-image \u001b[0m\u001b[1;36m \u001b[0m Command for generating a custom social share image. \u001b[2m│\u001b[0m\n",
"\u001b[2m╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n"
]
diff --git a/nbs/CLI_Docs_Generator.ipynb b/nbs/CLI_Docs_Generator.ipynb
new file mode 100644
index 00000000..392151aa
--- /dev/null
+++ b/nbs/CLI_Docs_Generator.ipynb
@@ -0,0 +1,264 @@
+{
+ "cells": [
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "9d0dcae3",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# | default_exp _components.cli_docs_generator"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "6482301e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# | export\n",
+ "\n",
+ "from typing import *\n",
+ "\n",
+ "from nbdev.quarto import nbdev_readme\n",
+ "from nbdev.config import get_config\n",
+ "from nbdev.doclinks import NbdevLookup\n",
+ "\n",
+ "from nbdev_mkdocs._helpers.doc_links_utils import fix_sym_links"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "70fa0abe",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "\n",
+ "import shutil\n",
+ "from pathlib import Path\n",
+ "from unittest.mock import patch, MagicMock\n",
+ "from contextlib import contextmanager\n",
+ "from tempfile import TemporaryDirectory\n",
+ "\n",
+ "from fastcore.foundation import Config"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3ef2a96d",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/mkdocs.html#prepare)\n"
+ ]
+ }
+ ],
+ "source": [
+ "@contextmanager\n",
+ "def mock_nbdev_readme(mock_contents, d):\n",
+ " with patch('__main__.nbdev_readme') as mock_nbdev_readme:\n",
+ " mock_nbdev_readme.__wrapped__ = MagicMock()\n",
+ " with open((Path(d) / \"README.md\"), \"w\", encoding=\"utf-8\") as f:\n",
+ " f.write(mock_contents)\n",
+ " yield\n",
+ " \n",
+ " \n",
+ "\n",
+ "_mock_nbdev_readme_return_value = \"\"\"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/mkdocs.html#prepare)\"\"\"\n",
+ "with TemporaryDirectory() as d:\n",
+ " with mock_nbdev_readme(_mock_nbdev_readme_return_value, d):\n",
+ " nbdev_readme.__wrapped__()\n",
+ " \n",
+ " with open((Path(d) / \"README.md\"), \"r\", encoding=\"utf-8\") as f:\n",
+ " contents = f.read()\n",
+ " \n",
+ " print(contents)\n",
+ " assert contents == _mock_nbdev_readme_return_value"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "ac8da600",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "/tmp/tmpna2i1g2b\n"
+ ]
+ }
+ ],
+ "source": [
+ "@contextmanager\n",
+ "def mock_get_config(d, cfg):\n",
+ " with patch(\"__main__.get_config\") as mock_get_config:\n",
+ " mock_get_config.return_value = cfg\n",
+ " yield\n",
+ "\n",
+ "with TemporaryDirectory() as d:\n",
+ " _d = dict(\n",
+ " config_path=Path(d),\n",
+ " doc_host=\"https://airtai.github.io\",\n",
+ " lib_path=Path(d) / \"nbdev_mkdocs\",\n",
+ " doc_baseurl=\"/nbdev-mkdocs\",\n",
+ " docs_versioning=\"minor\",\n",
+ " version=\"0.7.0rc0\",\n",
+ " lib_name=\"nbdev-mkdocs\",\n",
+ " )\n",
+ "\n",
+ " _types = dict(config_path=Path, doc_host=str, lib_path=Path, doc_baseurl=str, docs_versioning=str, version=str, lib_name=str)\n",
+ " cfg = Config(str(Path(d)), \"test_settings.ini\", create=_d, save=False, types=_types)\n",
+ " with mock_get_config(d, cfg):\n",
+ " cfg = get_config()\n",
+ "\n",
+ " print(cfg.config_path)\n",
+ " assert cfg.config_path == Path(d)\n",
+ " assert cfg.doc_host == 'https://airtai.github.io'\n",
+ " assert cfg.lib_path.name == 'nbdev_mkdocs'"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "dbfb735e",
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "# | export\n",
+ "\n",
+ "\n",
+ "def update_readme() -> None:\n",
+ " \"\"\"Update the readme file and fix the symbol links\"\"\"\n",
+ " cfg = get_config()\n",
+ " readme_path = cfg.config_path / \"README.md\"\n",
+ " nbdev_readme.__wrapped__()\n",
+ "\n",
+ " with open(readme_path, \"r\", encoding=\"utf-8\") as f:\n",
+ " contents = f.read()\n",
+ "\n",
+ " contents = fix_sym_links(\n",
+ " s=contents,\n",
+ " nbdev_lookup=NbdevLookup(incl_libs=cfg.lib_name.replace(\"_\", \"-\")),\n",
+ " docs_versioning=cfg.get(\"docs_versioning\", \"\"),\n",
+ " lib_version=cfg.version,\n",
+ " use_relative_doc_links=False,\n",
+ " use_latest_doc_version=True,\n",
+ " )\n",
+ "\n",
+ " with open(readme_path, \"w\", encoding=\"utf-8\") as f:\n",
+ " f.write(contents)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d52f9415",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\n",
+ "This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\n",
+ "This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\n",
+ "This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\n"
+ ]
+ }
+ ],
+ "source": [
+ "fixture = \"\"\"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/mkdocs.html#prepare)\"\"\"\n",
+ "expected = {\n",
+ " \"minor\": \"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\",\n",
+ " \"patch\": \"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\",\n",
+ " \"None\": \"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\"\n",
+ "}\n",
+ "\n",
+ "for docs_versioning in [\"minor\", \"patch\", \"None\", \"\"]:\n",
+ " with TemporaryDirectory() as d:\n",
+ " readme_path = Path(d) / \"README.md\"\n",
+ " _d = dict(\n",
+ " config_path=Path(d),\n",
+ " doc_host=\"https://airtai.github.io\",\n",
+ " lib_path=Path(d) / \"nbdev_mkdocs\",\n",
+ " doc_baseurl=\"/nbdev-mkdocs\",\n",
+ " docs_versioning=docs_versioning,\n",
+ " version=\"0.1.0\",\n",
+ " lib_name=\"nbdev-mkdocs\",\n",
+ " )\n",
+ "\n",
+ " _types = dict(config_path=Path, doc_host=str, lib_path=Path, doc_baseurl=str, docs_versioning=str, version=str, lib_name=str)\n",
+ " cfg = Config(str(Path(d)), \"test_settings.ini\", create=_d, save=False, types=_types)\n",
+ " with mock_get_config(d, cfg):\n",
+ " with mock_nbdev_readme(fixture, d):\n",
+ " update_readme()\n",
+ "\n",
+ " with open(readme_path, \"r\", encoding=\"utf-8\") as f:\n",
+ " actual = f.read()\n",
+ " print(actual)\n",
+ " if docs_versioning == \"\":\n",
+ " assert actual == expected[\"None\"]\n",
+ " else:\n",
+ " assert actual == expected[docs_versioning], f\"actual={actual}, expected={expected[doc_version]}\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "5fb1f459",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\n"
+ ]
+ }
+ ],
+ "source": [
+ "fixture = \"\"\"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/mkdocs.html#prepare)\"\"\"\n",
+ "expected = \"This is a link to a symbol [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\"\n",
+ "\n",
+ "with TemporaryDirectory() as d:\n",
+ " readme_path = Path(d) / \"README.md\"\n",
+ " _d = dict(\n",
+ " config_path=Path(d),\n",
+ " doc_host=\"https://airtai.github.io\",\n",
+ " lib_path=Path(d) / \"nbdev_mkdocs\",\n",
+ " doc_baseurl=\"/nbdev-mkdocs\",\n",
+ " version=\"0.1.0\",\n",
+ " lib_name=\"nbdev-mkdocs\",\n",
+ " )\n",
+ "\n",
+ " _types = dict(config_path=Path, doc_host=str, lib_path=Path, doc_baseurl=str, version=str, lib_name=str)\n",
+ " cfg = Config(str(Path(d)), \"test_settings.ini\", create=_d, save=False, types=_types)\n",
+ " with mock_get_config(d, cfg):\n",
+ " with mock_nbdev_readme(fixture, d):\n",
+ " update_readme()\n",
+ "\n",
+ " with open(readme_path, \"r\", encoding=\"utf-8\") as f:\n",
+ " actual = f.read()\n",
+ " print(actual)\n",
+ " assert actual == expected"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": "python3",
+ "language": "python",
+ "name": "python3"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
diff --git a/nbs/Doc_Links_Utils.ipynb b/nbs/Doc_Links_Utils.ipynb
index 02059b06..3a8b5546 100644
--- a/nbs/Doc_Links_Utils.ipynb
+++ b/nbs/Doc_Links_Utils.ipynb
@@ -376,7 +376,7 @@
"name": "stdout",
"output_type": "stream",
"text": [
- "\n",
+ "\n",
"fastkafka.FastKafka\n"
]
}
@@ -622,13 +622,19 @@
"# | export\n",
"\n",
"\n",
- "def _append_doc_version(fixed_part: str, docs_versioning: str, lib_version: str) -> str:\n",
+ "def _append_doc_version(\n",
+ " fixed_part: str,\n",
+ " docs_versioning: str,\n",
+ " lib_version: str,\n",
+ " use_latest_doc_version: bool,\n",
+ ") -> str:\n",
" \"\"\"Append the current version of the documentation to a URL.\n",
"\n",
" Args:\n",
" fixed_part: The fixed part of the URL.\n",
" docs_versioning: The value set for docs_versioning flag in settings.ini file.\n",
" lib_version: The version of the library.\n",
+ " use_latest_doc_version: If set to True, the latest version of the docs will be appended to the url.\n",
"\n",
" Returns:\n",
" The URL with the documentation version appended.\n",
@@ -637,11 +643,69 @@
"\n",
" The above docstring is autogenerated by docstring-gen library (https://docstring-gen.airt.ai)\n",
" \"\"\"\n",
- " return (\n",
- " f\"{fixed_part}/{_get_current_docs_version(docs_versioning, lib_version)}\"\n",
- " if docs_versioning != \"\" and docs_versioning != \"None\"\n",
- " else fixed_part\n",
- " )"
+ " if docs_versioning != \"\" and docs_versioning != \"None\":\n",
+ " return (\n",
+ " f\"{fixed_part}/latest\"\n",
+ " if use_latest_doc_version\n",
+ " else f\"{fixed_part}/{_get_current_docs_version(docs_versioning, lib_version)}\"\n",
+ " )\n",
+ " return fixed_part"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "c9235d80",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "https://airtai.github.io/fastkafka/latest\n",
+ "https://airtai.github.io/fastkafka/latest\n"
+ ]
+ }
+ ],
+ "source": [
+ "for docs_versioning in [\"minor\", \"patch\"]:\n",
+ " fixed_part = \"https://airtai.github.io/fastkafka\"\n",
+ " lib_version = \"0.0.1\"\n",
+ " use_latest_doc_version = True\n",
+ "\n",
+ " expected = \"https://airtai.github.io/fastkafka/latest\"\n",
+ " actual = _append_doc_version(fixed_part, docs_versioning, lib_version, use_latest_doc_version)\n",
+ " print(actual)\n",
+ "\n",
+ " assert actual == expected"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "d167a9af",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "https://airtai.github.io/fastkafka\n",
+ "https://airtai.github.io/fastkafka\n"
+ ]
+ }
+ ],
+ "source": [
+ "for docs_versioning in [\"\", \"None\"]:\n",
+ " fixed_part = \"https://airtai.github.io/fastkafka\"\n",
+ " lib_version = \"0.0.1\"\n",
+ " use_latest_doc_version = True\n",
+ "\n",
+ " expected = \"https://airtai.github.io/fastkafka\"\n",
+ " actual = _append_doc_version(fixed_part, docs_versioning, lib_version, use_latest_doc_version)\n",
+ " print(actual)\n",
+ "\n",
+ " assert actual == expected"
]
},
{
@@ -662,9 +726,10 @@
"fixed_part = \"https://airtai.github.io/fastkafka\"\n",
"docs_versioning = \"\"\n",
"lib_version = \"0.0.1\"\n",
+ "use_latest_doc_version = False\n",
"\n",
"expected = \"https://airtai.github.io/fastkafka\"\n",
- "actual = _append_doc_version(fixed_part, docs_versioning, lib_version)\n",
+ "actual = _append_doc_version(fixed_part, docs_versioning, lib_version, use_latest_doc_version)\n",
"print(actual)\n",
"\n",
"assert actual == expected"
@@ -688,9 +753,10 @@
"fixed_part = \"https://airtai.github.io/fastkafka\"\n",
"docs_versioning = \"None\"\n",
"lib_version = \"0.0.1\"\n",
+ "use_latest_doc_version = False\n",
"\n",
"expected = \"https://airtai.github.io/fastkafka\"\n",
- "actual = _append_doc_version(fixed_part, docs_versioning, lib_version)\n",
+ "actual = _append_doc_version(fixed_part, docs_versioning, lib_version, use_latest_doc_version)\n",
"print(actual)\n",
"\n",
"assert actual == expected"
@@ -714,9 +780,10 @@
"fixed_part = \"https://airtai.github.io/fastkafka\"\n",
"docs_versioning = \"minor\"\n",
"lib_version = \"0.1.0\"\n",
+ "use_latest_doc_version = False\n",
"\n",
"expected = \"https://airtai.github.io/fastkafka/0.1\"\n",
- "actual = _append_doc_version(fixed_part, docs_versioning, lib_version)\n",
+ "actual = _append_doc_version(fixed_part, docs_versioning, lib_version, use_latest_doc_version)\n",
"print(actual)\n",
"\n",
"assert actual == expected"
@@ -740,9 +807,10 @@
"fixed_part = \"https://airtai.github.io/fastkafka\"\n",
"docs_versioning = \"patch\"\n",
"lib_version = \"0.1.0\"\n",
+ "use_latest_doc_version = False\n",
"\n",
"expected = \"https://airtai.github.io/fastkafka/0.1.0\"\n",
- "actual = _append_doc_version(fixed_part, docs_versioning, lib_version)\n",
+ "actual = _append_doc_version(fixed_part, docs_versioning, lib_version, use_latest_doc_version)\n",
"print(actual)\n",
"\n",
"assert actual == expected"
@@ -977,6 +1045,7 @@
" docs_versioning: str,\n",
" lib_version: str,\n",
" use_relative_doc_links: bool,\n",
+ " use_latest_doc_version: bool,\n",
") -> str:\n",
" \"\"\"Update the link of a symbol\n",
"\n",
@@ -988,6 +1057,7 @@
" lib_version: The current version of the library\n",
" use_relative_doc_links: If set to True, relative link to symbols will be add in the generated\n",
" documentation for easier local navigation\n",
+ " use_latest_doc_version: If set to True, the latest version of the docs will be appended to the symbol link.\n",
"\n",
" Returns:\n",
" The updated link\n",
@@ -998,9 +1068,8 @@
" \"\"\"\n",
" fixed_part = \"/\".join(symbol_details[0].split(\"/\")[:4])\n",
" fixed_part_with_docs_version = _append_doc_version(\n",
- " fixed_part, docs_versioning, lib_version\n",
+ " fixed_part, docs_versioning, lib_version, use_latest_doc_version\n",
" )\n",
- "\n",
" full_symbol_path = _get_sym_path_from_nbdev_lookup(nbdev_lookup, symbol_details)\n",
" o = _import_symbol(full_symbol_path)\n",
" relative_sym_path = _get_relative_sym_path(o)\n",
@@ -1012,6 +1081,56 @@
" return updated_link"
]
},
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "3689e8e4",
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\n",
+ "[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\n",
+ "[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/latest/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\n",
+ "[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/latest/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\n"
+ ]
+ }
+ ],
+ "source": [
+ "expected = [\n",
+ " \"[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\",\n",
+ " \"[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\",\n",
+ " \"[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/latest/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\",\n",
+ " \"[`fastkafka.FastKafka.get_topics`](https://airtai.github.io/fastkafka/latest/api/fastkafka/FastKafka/#fastkafka._application.app.FastKafka.get_topics)\",\n",
+ "]\n",
+ "with mock_fastkafka_nbdev_loopup() as mock_nbdev_lookup:\n",
+ " with mock_fastkafka():\n",
+ " symbol = \"fastkafka.FastKafka.get_topics\"\n",
+ " symbol_details = (\n",
+ " \"https://airtai.github.io/fastkafka/fastkafka.html#fastkafka.get_topics\",\n",
+ " \"fastkafka/_application/app.py\",\n",
+ " \"https://github.com/airtai/fastkafka/blob/main/fastkafka/_application/app.py\",\n",
+ " )\n",
+ " docs_versioning = \"\"\n",
+ " lib_version = \"0.0.1\"\n",
+ "\n",
+ " for i, docs_versioning in enumerate([\"\", \"None\", \"minor\", \"patch\"]):\n",
+ " actual = _update_link(\n",
+ " symbol,\n",
+ " symbol_details,\n",
+ " mock_nbdev_lookup,\n",
+ " docs_versioning,\n",
+ " lib_version,\n",
+ " False,\n",
+ " True\n",
+ " )\n",
+ " print(actual)\n",
+ "\n",
+ " assert actual == expected[i], actual"
+ ]
+ },
{
"cell_type": "code",
"execution_count": null,
@@ -1055,6 +1174,7 @@
" docs_versioning,\n",
" lib_version,\n",
" use_relative_doc_links,\n",
+ " False\n",
" )\n",
" print(actual)\n",
"\n",
@@ -1104,6 +1224,7 @@
" docs_versioning,\n",
" lib_version,\n",
" use_relative_doc_links,\n",
+ " False\n",
" )\n",
" print(actual)\n",
"\n",
@@ -1148,6 +1269,7 @@
" docs_versioning,\n",
" lib_version,\n",
" use_relative_doc_links,\n",
+ " False\n",
" )\n",
" print(actual)\n",
"\n",
@@ -1193,6 +1315,7 @@
" docs_versioning,\n",
" lib_version,\n",
" use_relative_doc_links,\n",
+ " False,\n",
" )\n",
" print(actual)\n",
"\n",
@@ -1236,6 +1359,7 @@
" docs_versioning,\n",
" lib_version,\n",
" use_relative_doc_links,\n",
+ " False\n",
" )\n",
"\n",
" expected = \"[`nbdev_mkdocs.mkdocs.prepare`](https://airtai.github.io/nbdev-mkdocs/0.0.1rc0/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\"\n",
@@ -1247,11 +1371,12 @@
"for docs_versioning in [\"minor\", \"patch\"]:\n",
" actual = _update_link(\n",
" symbol,\n",
- " symbol_details,\n",
- " nbdev_lookup,\n",
- " docs_versioning,\n",
- " lib_version,\n",
- " use_relative_doc_links,\n",
+ " symbol_details=symbol_details,\n",
+ " nbdev_lookup=nbdev_lookup,\n",
+ " docs_versioning=docs_versioning,\n",
+ " lib_version=lib_version,\n",
+ " use_relative_doc_links=use_relative_doc_links,\n",
+ " use_latest_doc_version=False\n",
" )\n",
"\n",
" expected = \"[`nbdev_mkdocs.mkdocs.prepare`](api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\"\n",
@@ -1270,7 +1395,7 @@
"# | export\n",
"\n",
"\n",
- "def fix_sym_links(s: str, nbdev_lookup: NbdevLookup, docs_versioning: str, lib_version: str, use_relative_doc_links: bool) -> str: # type: ignore\n",
+ "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\n",
" \"\"\"Fix the default sym links generated by nbdev in the given string.\n",
"\n",
" Args:\n",
@@ -1280,6 +1405,7 @@
" lib_version: The current version of the library.\n",
" use_relative_doc_links: If set to True, relative link to symbols will be add in the generated\n",
" documentation for easier local navigation.\n",
+ " use_latest_doc_version: If set to True, the latest version of the docs will be appended to the symbol link.\n",
"\n",
" Returns:\n",
" The string with correct links added to the symbol references.\n",
@@ -1300,11 +1426,92 @@
" docs_versioning,\n",
" lib_version,\n",
" use_relative_doc_links,\n",
+ " use_latest_doc_version,\n",
" )\n",
" s = s.replace(match, updated_link)\n",
" return s"
]
},
+ {
+ "cell_type": "code",
+ "execution_count": null,
+ "id": "c51b5d6a",
+ "metadata": {},
+ "outputs": [
+ {
+ "data": {
+ "text/plain": [
+ "'This is a link to a symbol: [`prepare`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)'"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/plain": [
+ "'This is a link to a symbol: [`nbdev_mkdocs.mkdocs.prepare`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)'"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/plain": [
+ "'This is a link to a symbol: [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)'"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ },
+ {
+ "data": {
+ "text/plain": [
+ "'This is a link to a symbol: [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)'"
+ ]
+ },
+ "metadata": {},
+ "output_type": "display_data"
+ }
+ ],
+ "source": [
+ "nbdev_lookup = NbdevLookup(incl_libs=\"nbdev-mkdocs\")\n",
+ "docs_versioning = \"patch\"\n",
+ "lib_version = \"0.1.1\"\n",
+ "\n",
+ "use_relative_doc_links = False\n",
+ "use_latest_doc_version = True\n",
+ "for symbol in [\"prepare\", \"nbdev_mkdocs.mkdocs.prepare\"]:\n",
+ " fixture = f\"This is a link to a symbol: [`{symbol}`](https://airtai.github.io/nbdev-mkdocs/mkdocs.html#prepare)\"\n",
+ " expected = f\"This is a link to a symbol: [`{symbol}`](https://airtai.github.io/nbdev-mkdocs/latest/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\"\n",
+ " actual = fix_sym_links(\n",
+ " fixture,\n",
+ " nbdev_lookup,\n",
+ " docs_versioning,\n",
+ " lib_version,\n",
+ " use_relative_doc_links,\n",
+ " use_latest_doc_version,\n",
+ " )\n",
+ " display(actual)\n",
+ " assert actual == expected\n",
+ "\n",
+ "\n",
+ "fixture = f\"This is a link to a symbol: [`prepare`](https://airtai.github.io/nbdev-mkdocs/mkdocs.html#prepare)\"\n",
+ "expected = f\"This is a link to a symbol: [`prepare`](https://airtai.github.io/nbdev-mkdocs/api/nbdev_mkdocs/mkdocs/prepare/#nbdev_mkdocs.mkdocs.prepare)\"\n",
+ "for docs_versioning in [\"\", \"None\"]:\n",
+ " actual = fix_sym_links(\n",
+ " fixture,\n",
+ " nbdev_lookup,\n",
+ " docs_versioning,\n",
+ " lib_version,\n",
+ " use_relative_doc_links,\n",
+ " use_latest_doc_version,\n",
+ " )\n",
+ " display(actual)\n",
+ " assert actual == expected, expected"
+ ]
+ },
{
"cell_type": "code",
"execution_count": null,
diff --git a/nbs/index.ipynb b/nbs/index.ipynb
index 83e05788..2bfed6ed 100644
--- a/nbs/index.ipynb
+++ b/nbs/index.ipynb
@@ -248,17 +248,21 @@
"\u001b[2m╭─\u001b[0m\u001b[2m Commands \u001b[0m\u001b[2m──────────────────────────────────────────────────────────────────\u001b[0m\u001b[2m─╮\u001b[0m\r\n",
"\u001b[2m│\u001b[0m \u001b[1;36mdelete-pre-release-docs\u001b[0m\u001b[1;36m \u001b[0m Deletes deployed pre-release documentation \u001b[2m│\u001b[0m\r\n",
"\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m versions. \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mdocs \u001b[0m\u001b[1;36m \u001b[0m Prepares files in **mkdocs/docs** and then runs \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m **mkdocs build** command on them \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mdocs \u001b[0m\u001b[1;36m \u001b[0m Prepares files in 'mkdocs/docs' and then runs \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m 'mkdocs build' command on them. \u001b[2m│\u001b[0m\r\n",
"\u001b[2m│\u001b[0m \u001b[1;36mdocstring \u001b[0m\u001b[1;36m \u001b[0m Command for adding docstrings to classes and \u001b[2m│\u001b[0m\r\n",
"\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m methods that don't have one using docstring-gen \u001b[2m│\u001b[0m\r\n",
"\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m library. \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mnew \u001b[0m\u001b[1;36m \u001b[0m Creates files in **mkdocs** subdirectory needed for \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m other **nbdev_mkdocs** subcommands \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mprepare \u001b[0m\u001b[1;36m \u001b[0m Runs tests and prepares files in **mkdocs/docs** \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m and then runs **mkdocs build** command on them \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36mpreview \u001b[0m\u001b[1;36m \u001b[0m Prepares files in **mkdocs/docs** and then runs \u001b[2m│\u001b[0m\r\n",
- "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m **mkdocs serve** command on them \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mnew \u001b[0m\u001b[1;36m \u001b[0m Creates files in 'mkdocs' subdirectory needed for \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m other 'nbdev_mkdocs' subcommands. \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mprepare \u001b[0m\u001b[1;36m \u001b[0m Runs tests and prepares files in 'mkdocs/docs' and \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m then runs 'mkdocs build' command on them. \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mpreview \u001b[0m\u001b[1;36m \u001b[0m Prepares files in 'mkdocs/docs' and then runs \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m 'mkdocs serve' command on them. \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36mreadme \u001b[0m\u001b[1;36m \u001b[0m Updates the README.md file from the 'readme_nb' \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m notebook. Unless explicitly changed in the \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m settings.ini file, the 'readme_nb' points to the \u001b[2m│\u001b[0m\r\n",
+ "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m 'index.ipynb' notebook in the 'nbs_path' directory. \u001b[2m│\u001b[0m\r\n",
"\u001b[2m│\u001b[0m \u001b[1;36msocial-image \u001b[0m\u001b[1;36m \u001b[0m Command for generating a custom social share image. \u001b[2m│\u001b[0m\r\n",
"\u001b[2m╰──────────────────────────────────────────────────────────────────────────────╯\u001b[0m\r\n",
"\r\n"
@@ -309,12 +313,22 @@
"source": [
"#### Prepare changes\n",
"\n",
- "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.\n",
+ "To prepare your changes for Git push, we recommend executing the following commands:\n",
+ "\n",
+ "First, run the `nbdev_mkdocs prepare` command in the terminal. This command exports the library, runs tests, and cleans the notebooks.\n",
"\n",
"```shell\n",
"nbdev_mkdocs prepare\n",
"```\n",
"\n",
+ "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.\n",
+ "\n",
+ "This command does everything the 'nbdev_readme' command does, plus it generates symbol references that are compatible with 'Material for nbdev'.\n",
+ "\n",
+ "```shell\n",
+ "nbdev_mkdocs readme\n",
+ "```\n",
+ "\n",
"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:\n",
"\n",
"```shell\n",
diff --git a/settings.ini b/settings.ini
index 7341c9f0..fd0f6ac8 100644
--- a/settings.ini
+++ b/settings.ini
@@ -5,7 +5,7 @@
### Python library ###
repo = nbdev-mkdocs
lib_name = %(repo)s
-version = 0.6.0
+version = 0.7.0rc0
min_python = 3.8
license = apache2