maint: better doc/package handling

Author: yozachar

.github/workflows/docs.yaml.bkp

@@ -27,7 +27,7 @@ jobs:
           pip install .
           pip install -r package/requirements.mkdocs.txt
       - name: Build documentation
-        run: python src/export docs
+        run: python package/export docs
       # set up Pages
       - name: Set up Pages
         uses: actions/configure-pages@v3

.github/workflows/package.yaml

@@ -34,7 +34,7 @@ jobs:
       - name: Build package
         run: |
           . ./.venv/bin/activate
-          python src/export package
+          python package/export pkg
           deactivate
       # upload package as artifact
       - name: Upload artifact

MANIFEST.in

@@ -7,7 +7,6 @@ include .gitignore
 # global-include
 
 recursive-include tests *
-recursive-include src/export *
 
 # graft
 
@@ -16,6 +15,7 @@ recursive-include src/export *
 # global-exclude
 
 recursive-exclude docs *.rst
+recursive-exclude docs/references *.md
 
 prune docs/_build
 prune **/__pycache__

mkdocs.yaml

@@ -64,21 +64,3 @@ copyright: Copyright © 2013 - 2024 Konsta Vesterinen
 
 nav:
   - Home: index.md
-  - API:
-      - references/between.md
-      - references/btc_address.md
-      - references/card.md
-      - references/country_code.md
-      - references/domain.md
-      - references/email.md
-      - references/hashes.md
-      - references/hostname.md
-      - references/i18n.md
-      - references/iban.md
-      - references/ip_address.md
-      - references/length.md
-      - references/mac_address.md
-      - references/slug.md
-      - references/url.md
-      - references/utils.md
-      - references/uuid.md

src/export/__init__.py renamed to package/export/__init__.py

@@ -40,13 +40,13 @@ def _parse_package(source: Path):
 
 def _generate_reference(source: Path, destination: Path, ext: str):
     """Generate reference."""
-    nav_items: Dict[str, List[str]] = {"Code Reference": []}
+    nav_items: Dict[str, List[str]] = {"API": []}
     # generate reference content
     for module_name, aliases in _parse_package(source):
         for alias in aliases:
             _write_ref_content(destination / f"{module_name}.{ext}", module_name, alias.name)
         if ext == "md":
-            nav_items["Code Reference"].append(f"references/{module_name}.md")
+            nav_items["API"].append(f"references/{module_name}.md")
     return nav_items
 
 
@@ -65,6 +65,9 @@ def _update_mkdocs_config(source: Path, destination: Path, nav_items: Dict[str,
 
 def _gen_md_docs(source: Path, refs_path: Path):
     """Generate Markdown docs."""
+    # remove existing markdown files
+    for md_files in (source / "docs/references").glob("*.md"):
+        md_files.unlink()
     nav_items = _generate_reference(source / "src/validators/__init__.py", refs_path, "md")
     # backup mkdocs config
     _update_mkdocs_config(source / "mkdocs.yaml", source / "mkdocs.bak.yaml", nav_items)
@@ -166,7 +169,7 @@ def package(source: Path):
     if len(argv) != 2:
         quit(exit_code)
 
-    if argv[1] == "package":
+    if argv[1] == "pkg":
         exit_code = package(project_root)
     if argv[1] == "docs":
         exit_code = generate_documentation(

src/export/__main__.py renamed to package/export/__main__.py

@@ -46,7 +46,7 @@ if ($IsLinux || $IsMacOS) {
 . $venv_dir\$bin_path\Activate.ps1
 
 # Run export script
-python src/export package
+python package/export pkg
 
 # Deactivate virtual environment
 deactivate

package/roll.ps1

@@ -40,7 +40,7 @@ $venv_dir/bin/pip install build
 . $venv_dir/bin/activate
 
 # Run export script
-python src/export package
+python package/export pkg
 
 # Deactivate virtual environment
 deactivate