Merge branch 'main' into feature/salesforce-features

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'>

HISTORY.md

@@ -4,6 +4,29 @@ In the beginning, programmers created the databases. Now the databases were form
 
 And so [Salesforce.org](http://salesforce.org/) said “Let there be data,” and there was Snowfakery. And it was good.
 
+## Snowfakery 2.0
+
+Recipes can now merge in data from Salesforce orgs as
+records, IDs or datasets. (#395 and #401)
+
+Output streams can now be specified as 3rd party libraries. Any Python class name
+can be passed to --output-format as long as it adheres to the OutputStream
+protocol as shown in examples/YamlOutputStream.py (#351)
+
+Snowfakery is thread-safe/multi-processor-ready and available for parallel usage
+in CumulusCI. (CumulusCI Repo)
+
+Snowfakery now supports a --reps option as an easier way to repeat a recipe (#416)
+
+Snowfakery now accepts LeadingCaps syntax for all fakers, as well as
+underscore_separated and everythinglowercase. (#403)
+
+Salesforce.ContentVersion and Salesforce.ProfileId convenience functions were added
+(#421)
+
+Snowfakery now has voluminous documentation about Fakes in many languages and
+locales (#409)
+
 ## Snowfakery 1.12
 
 Fix a regression: In some contexts it was impossible to call Faker with either

LICENSE

@@ -1,27 +1,30 @@
-    Copyright (c) 2020, Salesforce.org
-    All rights reserved.
-    
-    Redistribution and use in source and binary forms, with or without
-    modification, are permitted provided that the following conditions are met:
-    
-    * Redistributions of source code must retain the above copyright
-      notice, this list of conditions and the following disclaimer.
-    * Redistributions in binary form must reproduce the above copyright
-      notice, this list of conditions and the following disclaimer in the
-      documentation and/or other materials provided with the distribution.
-    * Neither the name of Salesforce.org nor the names of
-      its contributors may be used to endorse or promote products derived
-      from this software without specific prior written permission.
+Copyright (c) 2021, Salesforce.com, Inc.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the
+  above copyright notice, this list of conditions
+  and the following disclaimer.
+
+* Redistributions in binary form must reproduce
+  the above copyright notice, this list of conditions
+  and the following disclaimer in the documentation
+  and/or other materials provided with the distribution.
+
+* Neither the name of Salesforce.com nor the names
+  of its contributors may be used to endorse or promote
+  products derived from this software without specific
+  prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
+BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
+WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
-    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
-    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
-    COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
-    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
-    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
-    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
-    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
-    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
-    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
-    POSSIBILITY OF SUCH DAMAGE.

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"]