Replace sphinx with mkdocs as default docs option, add none option (#295

)

* create alternative mkdocs docs path and add option to use sphinx, mkdocs, or none

* add tests that docs folder looks correct

* add author if provided to mkdocs config

* fix yml typo

* make mkdocs default, do not remove sphinx yet

* reconfigure tests to cycle through all possible values for fields that are nominally independent

* change formatting

* cast docs paths to strings to satisfy shutil move in python 3.8

* remove sphinx

* remove docs folder tree; make docs removal generic

.gitignore

@@ -85,9 +85,6 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
-
 # PyBuilder
 .pybuilder/
 target/

README.md

@@ -45,7 +45,7 @@ The directory structure of your new project will look something like this (depen
 │   ├── processed      <- The final, canonical data sets for modeling.
 │   └── raw            <- The original, immutable data dump.
 │
-├── docs               <- A default Sphinx project; see sphinx-doc.org for details
+├── docs               <- A default mkdocs project; see mkdocs.org for details
 │
 ├── models             <- Trained and serialized models, model predictions, or model summaries
 │

ccds.json

@@ -11,7 +11,7 @@
         {"s3": {"bucket": "bucket-name", "aws_profile": "default"}},
         {"gcs": {"bucket": "bucket-name"}}
     ],
-    "environment_manager" : [
+    "environment_manager": [
         "virtualenv",
         "conda",
         "pipenv",
@@ -27,5 +27,6 @@
         "basic"
     ],
     "open_source_license": ["No license file", "MIT", "BSD-3-Clause"],
+    "docs": ["mkdocs", "none"],
     "include_code_scaffold": ["Yes", "No"]
-}
+}

docs/docs/index.md

@@ -54,7 +54,7 @@ Disagree with a couple of the default folder names? Working on a project that's
 
 ## Getting started
 
-With this in mind, we've created a data science cookiecutter template for projects in Python. Your analysis doesn't have to be in Python, but the template does provide some Python boilerplate that you'd want to remove (in the `{{ cookiecutter.module_name }}` folder for example, and the Sphinx documentation skeleton in `docs`).
+With this in mind, we've created a data science cookiecutter template for projects in Python. Your analysis doesn't have to be in Python, but the template does provide some Python boilerplate that you'd want to remove (in the `{{ cookiecutter.module_name }}` folder for example, and the mkdocs documentation skeleton in `docs`).
 
 > ℹ️ Cookiecutter Data Science v2 has changed from v1. It now requires installing the new cookiecutter-data-science Python package, which extends the functionality of the [cookiecutter](https://cookiecutter.readthedocs.io/en/stable/README.html) templating utility. Use the provided `ccds` command-line program instead of `cookiecutter`.
 
@@ -99,7 +99,7 @@ The directory structure of your new project will look something like this (depen
 │   ├── processed      <- The final, canonical data sets for modeling.
 │   └── raw            <- The original, immutable data dump.
 │
-├── docs               <- A default Sphinx project; see sphinx-doc.org for details
+├── docs               <- A default mkdocs project; see www.mkdocs.org for details
 │
 ├── models             <- Trained and serialized models, model predictions, or model summaries
 │

hooks/post_gen_project.py

@@ -47,6 +47,22 @@
     "python-dotenv",
 ]
 
+# Use the selected documentation package specified in the config,
+# or none if none selected
+docs_path = Path("docs")
+# {% if cookiecutter.docs != "none" %}
+packages += ["{{ cookiecutter.docs }}"]
+pip_only_packages += ["{{ cookiecutter.docs }}"]
+docs_subpath = docs_path / "{{ cookiecutter.docs }}"
+for obj in docs_subpath.iterdir():
+    shutil.move(str(obj), str(docs_path))
+# {% endif %}
+
+# Remove all remaining docs templates
+for docs_template in docs_path.iterdir():
+    if docs_template.is_dir() and not docs_template.name == "docs":
+        shutil.rmtree(docs_template)
+
 #
 #  POST-GENERATION FUNCTIONS
 #

tests/conftest.py

@@ -3,7 +3,7 @@
 import sys
 import tempfile
 from contextlib import contextmanager
-from itertools import product
+from itertools import cycle, product
 from pathlib import Path
 
 import pytest
@@ -19,8 +19,6 @@
     "module_name": "project_module",
     "author_name": "DrivenData",
     "description": "A test project",
-    "open_source_license": "MIT",
-    "dataset_storage": {"azure": {"container": "container-name"}},
 }
 
 
@@ -58,14 +56,23 @@ def _is_valid(config):
 
     # remove invalid configs
     configs = [c for c in configs if _is_valid(c)]
-    include_code_scaffold = True
+
+    # cycle over all values other multi-select fields that should be inter-operable
+    # and that we don't need to handle with combinatorics
+    cycle_fields = [
+        "dataset_storage",
+        "open_source_license",
+        "include_code_scaffold",
+        "docs",
+    ]
+    cyclers = {k: cycle(cookiecutter_json[k]) for k in cycle_fields}
 
     for ind, c in enumerate(configs):
         config = dict(c)
         config.update(default_args)
         # Alternate including the code scaffold
-        config["include_code_scaffold"] = "Yes" if include_code_scaffold else "No"
-        include_code_scaffold = not include_code_scaffold
+        for field, cycler in cyclers.items():
+            config[field] = next(cycler)
         config["repo_name"] += f"-{ind}"
         yield config
 

tests/test_creation.py

@@ -60,6 +60,9 @@ def verify_folders(root, config):
             f"{config['module_name']}/visualization",
         ]
 
+    if config["docs"] == "mkdocs":
+        expected_dirs += ["docs/docs"]
+
     expected_dirs = [
         #  (root / d).resolve().relative_to(root) for d in expected_dirs
         Path(d)
@@ -86,12 +89,7 @@ def verify_files(root, config):
         "data/interim/.gitkeep",
         "data/processed/.gitkeep",
         "data/raw/.gitkeep",
-        "docs/Makefile",
-        "docs/commands.rst",
-        "docs/conf.py",
-        "docs/getting-started.rst",
-        "docs/index.rst",
-        "docs/make.bat",
+        "docs/.gitkeep",
         "notebooks/.gitkeep",
         "references/.gitkeep",
         "reports/.gitkeep",
@@ -117,6 +115,14 @@ def verify_files(root, config):
             f"{config['module_name']}/visualization/visualize.py",
         ]
 
+    if config["docs"] == "mkdocs":
+        expected_files += [
+            "docs/mkdocs.yml",
+            "docs/README.md",
+            "docs/docs/index.md",
+            "docs/docs/getting-started.md",
+        ]
+
     expected_files.append(config["dependency_file"])
 
     expected_files = [Path(f) for f in expected_files]

{{ cookiecutter.repo_name }}/.gitignore

@@ -80,8 +80,8 @@ instance/
 # Scrapy stuff:
 .scrapy
 
-# Sphinx documentation
-docs/_build/
+# MkDocs documentation
+docs/site/
 
 # PyBuilder
 .pybuilder/

{{ cookiecutter.repo_name }}/README.md

@@ -14,7 +14,7 @@
 │   ├── processed      <- The final, canonical data sets for modeling.
 │   └── raw            <- The original, immutable data dump.
 │
-├── docs               <- A default Sphinx project; see sphinx-doc.org for details
+├── docs               <- A default mkdocs project; see mkdocs.org for details
 │
 ├── models             <- Trained and serialized models, model predictions, or model summaries
 │