feat: converting documentation to mkdocs

Author: gvwilson

.gitignore

@@ -13,6 +13,8 @@ tests/test_orca/images/linux/failed/
 
 doc/python/raw.githubusercontent.com/
 
+docs/
+
 # Don't ignore dataset files
 !*.csv.gz
 !*.geojson.gz

CONTRIBUTING.md

@@ -8,7 +8,7 @@ then explains the technical aspects of preparing your contribution.
 
 ## Code of Conduct
 
-Please note that all contributos are required to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+Please note that all contributos are required to abide by our Code of Conduct.
 
 ## Different Ways to Contribute
 
@@ -38,7 +38,7 @@ it is important to understand the structure of the code and the repository.
     These are organized in subdirectories according to what they test:
     see the "Setup" section below for more details.
 
--   Documentation is found in `doc/`, and its structure is described in [its README file](doc/README.md).
+-   Documentation is found in `doc/`, and its structure is described in its README file.
     The documentation is a great place to start contributing,
     since you can add or modify examples without setting up a full environment.
 

mkdocs.yml

@@ -0,0 +1,40 @@
+site_name: "Plotly.py Docs"
+docs_dir: pages
+site_dir: docs
+
+plugins:
+  - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
+  - mkdocstrings:
+      handlers:
+        python:
+          options:
+            docstring_style: google
+            show_source: false
+            show_root_heading: true
+            show_root_toc_entry: true
+            merge_init_into_class: true
+
+nav:
+- Home: index.md
+- API Reference: reference/
+- Project:
+  - license.md
+  - conduct.md
+  - contributing.md
+
+theme:
+  name: "material"
+
+markdown_extensions:
+- def_list
+- markdown_include.include:
+    base_path: docs
+- footnotes
+
+exclude_docs: >
+  *~

pages/conduct.md

@@ -0,0 +1 @@
+{!../CODE_OF_CONDUCT.md!}

pages/contributing.md

@@ -0,0 +1 @@
+{!../CONTRIBUTING.md!}

pages/index.md

@@ -0,0 +1 @@
+{!../README.md!}

pages/license.md

@@ -0,0 +1 @@
+{!../LICENSE.txt!}

pyproject.toml

@@ -50,7 +50,13 @@ dev_core = [
 dev_build = [
     "plotly[dev_core]",
     "build",
-    "jupyter"
+    "jupyter",
+    "markdown-include",
+    "mkdocs",
+    "mkdocs-material",
+    "mkdocstrings[python]",
+    "mkdocs-gen-files",
+    "mkdocs-literate-nav"
 ]
 dev_optional = [
     "plotly[dev_build]",

scripts/gen_ref_pages.py

@@ -0,0 +1,32 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("plotly").rglob("*.py")):
+    module_path = path.relative_to(".").with_suffix("")
+    doc_path = path.relative_to(".").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"# {ident}\n\n")
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())