* set up mkdocs locally (mkdocs.yml and gen_ref_pages.py)

* added index.md, CONTRIBUTING.md, about.md * added the generated folder to gitignore * added logos in the README.md
flatironinstitute · Jun 13, 2023 · aed9a4d · aed9a4d
1 parent c0935d4
commit aed9a4d
Show file tree

Hide file tree

Showing 13 changed files with 119 additions and 1 deletion.
diff --git a/.gitignore b/.gitignore
@@ -134,3 +134,5 @@ dmypy.json
 
 .DS_Store
 
+# mkdocs generated folder
+docs/generated/
diff --git a/CCN-letterFoot.png b/CCN-letterFoot.png
diff --git a/CCN-logo-wText.png b/CCN-logo-wText.png
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
diff --git a/README.md b/README.md
@@ -1,3 +1,5 @@
+![LOGO](CCN-logo-wText.png)
+
 # generalized-linear-models
 Toolbox for basic Generalized Linear Models (GLMs) for neural data analysis
 
@@ -18,3 +20,5 @@ without `jax` and `jaxlib` already installed, so either run this before the
 earlier `pip install` command or uninstall them first (`pip uninstall jax
 jaxlib`). See [jax docs](https://github.com/google/jax#conda-installation) for
 details (the `pip` instructions did not work for me).
+
+![FOOT](CCN-letterFoot.png)
diff --git a/about.md b/about.md
diff --git a/docs/examples/README.md b/docs/examples/README.md
@@ -0,0 +1,19 @@
+# Examples
+
+This page consists of the 'General example' gallery and a sub-gallery,
+'No image output examples'. This sub-gallery is generated from a
+sub-directory within the general examples directory. The file structure of
+this gallery looks like this:
+
+```
+examples/           # base 'Gallery of Examples' directory
+├── README.md
+├── test_example.py
+├── test_myClass.py
+├── <.py files>
+```
+
+## General examples
+
+This gallery consists of introductory examples and examples demonstrating
+specific features of Mkdocs-Gallery.
diff --git a/docs/examples/test_example.py b/docs/examples/test_example.py
@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+"""
+A short Python script
+=====================
+
+This demonstrates an example `.py` file that is not executed when gallery is
+generated (see
+[Parsing and executing examples via matching patterns](https://sphinx-gallery.github.io/stable/configuration.html#build-pattern))
+but nevertheless gets included as an example. Note that no output is captured as this file is not executed.
+"""
+
+# Code source: Óscar Nájera
+# License: BSD 3 clause
+
+from __future__ import print_function
+print([i for i in range(10)])
diff --git a/docs/examples/test_myClass.py b/docs/examples/test_myClass.py
@@ -0,0 +1,11 @@
+"""
+Example myClass
+
+Local module
+============
+
+This example demonstrates how local modules can be imported.
+This module is imported in the example
+"""
+
+N = 200
diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
@@ -0,0 +1,31 @@
+"""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("src").rglob("*.py")):
+    module_path = path.relative_to("src").with_suffix("")
+    doc_path = path.relative_to("src").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}")
+
+    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())
diff --git a/index.md b/index.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,28 @@
+site_name: ccn-template
+repo_url: https://github.com/flatironinstitute/ccn-template
+
+theme:
+  name: 'material'
+  palette:
+    primary: 'light blue'
+    features:
+      - navigation.tabs
+plugins:
+  - search  # make sure the search plugin is still enabled
+  - mkdocstrings
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - literate-nav:
+        nav_file: docs/SUMMARY.md
+  - section-index
+  - gallery:
+      examples_dirs: docs/examples          # path to your example scripts
+      gallery_dirs: docs/generated/gallery  # where to save generated gallery
+  #     # ... (other options)
+nav:
+    - Home: index.md
+    - Tutorials: generated/gallery
+    - Contributing: CONTRIBUTING.md
+    - Code References: reference/
+    - About: about.md
diff --git a/pyproject.toml b/pyproject.toml
@@ -48,7 +48,14 @@ dev = [
   "pytest",
   "flake8",
   "coverage",
-  "pytest-cov"
+  "pytest-cov",
+  "mkdocs",
+  "mkdocstrings[python]",
+  "mkdocs_section_index",
+  "mkdocs_gen_files",
+  "mkdocs_literate_nav",
+  "mkdocs-gallery",
+  "pillow'
   ]
Original file line number	Diff line number	Diff line change
Expand Up		@@ -134,3 +134,5 @@ dmypy.json

		.DS_Store

		# mkdocs generated folder
		docs/generated/