Merge pull request #409 from SFDO-Tooling/feature/fake-data-docs

First pass at adding Faker docs

Author: Paul Prescod

.github/workflows/ci.yml

@@ -56,6 +56,25 @@ jobs:
       - name: Run Tests
         run: python -m pytest
 
+  faker_docs:
+    name: Faker Docs
+    runs-on: ubuntu-latest
+    steps:
+      - uses: "actions/checkout@v2"
+      - uses: "actions/setup-python@v1"
+        with:
+          python-version: "3.9"
+
+      - name: Install dependencies
+        run: |
+          python -VV
+          python -m pip install --upgrade pip pip-tools
+          make dev-install
+          python setup.py install
+
+      - name: Make Docs
+        run: make docs
+
   windows:
     name: Windows ${{ matrix.python-version }}
     runs-on: windows-latest

.gitignore

@@ -13,6 +13,9 @@ build/
 dist/
 docs/api/
 docs/_build/
+docs/fakedata
+docs/fakedata.md
+docs/locales.md
 .eggs/
 .idea/
 .tox/

CONTRIBUTING.rst

@@ -71,7 +71,13 @@ Or you could make it outside of the project repo.
 
     $ pytest
 
-7. Your new code should also have meaningful tests. One way to double check that
+7. Build the docs like this: 
+    $ make docs
+    $ open build/html/index.html
+
+Set SF_MKDOCS_BUILD_LOCALES=False to skip building all locales
+
+8. Your new code should also have meaningful tests. One way to double check that
    your tests cover everything is to ensure that your new code has test code coverage:
 
    $ pytest --cov
@@ -123,3 +129,27 @@ You can finish up the process by updating the release object that was auto-creat
 Just paste in the changelog notes and hit publish. 
 
 Tada! You've published a new version of Snowfakery.
+
+Internal Software Architecture
+------------------------------
+
+===================================  ================================  
+Filename	                         Purpose	
+-----------------------------------  --------------------------------
+
+cli.py	                             Click-based Command Line. Uses the Click library to supply a CLI.
+data_generator.py	                 The API entry point the CLI and CCI use. <p>This may be the best place to start reading. It abstracts away all of the complexity and outlines the core flow.	
+parse_recipe_yaml.py	             Phase 1: parse YAML into a Runtime DOM<p>Includes some hacks to the YAML parser for handling line numbers.	
+data_generator_runtime.py	         Phase 2: Runtime.<p>Actually generate the data by walking the template list top-to-bottom, generating rows as appopriate. 	
+data_generator_runtime_dom.py	     An object model used in Phase 2. Roughly similar to the shape of the YAML file.
+output_streams.py	                 Where the data goes in the output. Used during Phase 2.	
+data_gen_exceptions.py	             Exceptions that can be thrown	
+generate_mapping_from_recipe.py	     In the CCI context, this utility package allows the generation of mapping.yml files.	
+template_funcs.py	                 Functions that can be invoked using either block syntax or in Jinja templates	
+plugins.py                           Infrastructure for plugins 
+standard_plugins/                    Plugins that ship with Snowfakery 
+tests/	                             Unit tests	
+===================================  ================================  
+
+
+<img src='docs/images/img6.png' id='PJUACA3lKvf' alt='Architecture Diagram'>

Makefile

@@ -5,3 +5,10 @@ update-deps:
 dev-install:
 	pip install --upgrade pip-tools
 	pip-sync requirements/*.txt
+	pip install -e .
+
+# set SF_MKDOCS_BUILD_LOCALES=False to skip building all locales
+docs:		.FORCE
+	python -m mkdocs build --clean --site-dir build/html --config-file mkdocs.yml
+
+.FORCE:

custom_theme/img/favicon.ico

@@ -27,8 +27,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["myst_parser"]
-myst_config = {}
+extensions = []
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]