[DOCS] Preparation for building api docs (great-expectations#6737)

lockettks · Jan 10, 2023 · 2d916aa · 2d916aa
1 parent cab1562
commit 2d916aa
Show file tree

Hide file tree

Showing 6 changed files with 119 additions and 44 deletions.
diff --git a/docs/build_docs b/docs/build_docs
@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Build API docs then build docusaurus docs.
+# Currently used in our netlify pipeline.
+# Note: Will be modified to build API docs on latest tagged release.
+
+echo "Installing dev dependencies"
+pip install -c constraints-dev.txt -e ".[test]"
+
+echo "Installing dev dependencies"
+(cd docs/sphinx_api_docs_source; pip install -r requirements-dev-api-docs.txt)
+
+echo "Building sphinx API docs."
+(cd docs/sphinx_api_docs_source; invoke docs)
+
+echo "Building docusaurus docs."
+yarn build
diff --git a/docs/sphinx_api_docs_source/build_sphinx_api_docs.py b/docs/sphinx_api_docs_source/build_sphinx_api_docs.py
@@ -208,11 +208,16 @@ def _build_class_md_stubs(self) -> None:
         for definition in definitions:
             if isinstance(definition.ast_definition, ast.ClassDef):
                 md_stub = self._create_class_md_stub(definition=definition)
-                self._write_stub(stub=md_stub, definition=definition)
+                self._write_stub(
+                    stub=md_stub,
+                    file_name=self._get_md_file_name_from_entity_name(
+                        definition=definition
+                    ),
+                )
 
-    def _write_stub(self, stub: str, definition: Definition) -> None:
+    def _write_stub(self, stub: str, file_name: str) -> None:
         """Write the markdown stub file with appropriate filename."""
-        filepath = self.base_path / self._get_md_file_name(definition=definition)
+        filepath = self.base_path / file_name
         with filepath.open("a") as f:
             f.write(stub)
 
@@ -223,17 +228,27 @@ def _build_module_md_stubs(self):
 
         for definition in definitions:
             md_stub = self._create_module_md_stub(definition=definition)
-            self._write_stub(stub=md_stub, definition=definition)
+            self._write_stub(
+                stub=md_stub,
+                file_name=self._get_md_file_name_from_dotted_path_prefix(
+                    definition=definition
+                ),
+            )
 
     def _get_entity_name(self, definition: Definition):
         """Get the name of the entity (class, module, function)."""
         return definition.ast_definition.name
 
-    def _get_md_file_name(self, definition: Definition):
+    def _get_md_file_name_from_entity_name(self, definition: Definition):
         """Generate markdown file name from the entity definition."""
         snake_name = camel_to_snake(self._get_entity_name(definition=definition))
         return f"{snake_name}.md"
 
+    def _get_md_file_name_from_dotted_path_prefix(self, definition: Definition):
+        """Generate markdown file name from the dotted path prefix."""
+        dotted_path_prefix = self._get_dotted_path_prefix(definition=definition)
+        return f"{dotted_path_prefix}.md"
+
     def _get_dotted_path_to_class(self, definition: Definition):
         """Get the dotted path to a class.
 

diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -219,15 +219,15 @@ module.exports = {
             html: `
                 <a class="footer__icon" href="https://greatexpectations.io/slack" target="_blank" rel="noreferrer noopener" aria-label="check out or Slack community">
                   <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M409.4 128c-42.4 0-76.7 34.4-76.7 76.8 0 20.3 8.1 39.9 22.4 54.3 14.4 14.4 33.9 22.5 54.3 22.5h76.7v-76.8c0-42.3-34.3-76.7-76.7-76.8zm0 204.8H204.7c-42.4 0-76.7 34.4-76.7 76.8s34.4 76.8 76.7 76.8h204.6c42.4 0 76.7-34.4 76.7-76.8.1-42.4-34.3-76.8-76.6-76.8zM614 486.4c42.4 0 76.8-34.4 76.7-76.8V204.8c0-42.4-34.3-76.8-76.7-76.8-42.4 0-76.7 34.4-76.7 76.8v204.8c0 42.5 34.3 76.8 76.7 76.8zm281.4-76.8c0-42.4-34.4-76.8-76.7-76.8S742 367.2 742 409.6v76.8h76.7c42.3 0 76.7-34.4 76.7-76.8zm-76.8 128H614c-42.4 0-76.7 34.4-76.7 76.8 0 20.3 8.1 39.9 22.4 54.3 14.4 14.4 33.9 22.5 54.3 22.5h204.6c42.4 0 76.7-34.4 76.7-76.8.1-42.4-34.3-76.7-76.7-76.8zM614 742.4h-76.7v76.8c0 42.4 34.4 76.8 76.7 76.8 42.4 0 76.8-34.4 76.7-76.8.1-42.4-34.3-76.7-76.7-76.8zM409.4 537.6c-42.4 0-76.7 34.4-76.7 76.8v204.8c0 42.4 34.4 76.8 76.7 76.8 42.4 0 76.8-34.4 76.7-76.8V614.4c0-20.3-8.1-39.9-22.4-54.3-14.4-14.4-34-22.5-54.3-22.5zM128 614.4c0 20.3 8.1 39.9 22.4 54.3 14.4 14.4 33.9 22.5 54.3 22.5 42.4 0 76.8-34.4 76.7-76.8v-76.8h-76.7c-42.3 0-76.7 34.4-76.7 76.8z"></path></svg>
-                </a> 
+                </a>
                 <a class="footer__icon" href="https://twitter.com/expectgreatdata" target="_blank" rel="noreferrer noopener" aria-label="check out or Slack community">
-                  <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M928 254.3c-30.6 13.2-63.9 22.7-98.2 26.4a170.1 170.1 0 0 0 75-94 336.64 336.64 0 0 1-108.2 41.2A170.1 170.1 0 0 0 672 174c-94.5 0-170.5 76.6-170.5 170.6 0 13.2 1.6 26.4 4.2 39.1-141.5-7.4-267.7-75-351.6-178.5a169.32 169.32 0 0 0-23.2 86.1c0 59.2 30.1 111.4 76 142.1a172 172 0 0 1-77.1-21.7v2.1c0 82.9 58.6 151.6 136.7 167.4a180.6 180.6 0 0 1-44.9 5.8c-11.1 0-21.6-1.1-32.2-2.6C211 652 273.9 701.1 348.8 702.7c-58.6 45.9-132 72.9-211.7 72.9-14.3 0-27.5-.5-41.2-2.1C171.5 822 261.2 850 357.8 850 671.4 850 843 590.2 843 364.7c0-7.4 0-14.8-.5-22.2 33.2-24.3 62.3-54.4 85.5-88.2z"></path></svg>                
+                  <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M928 254.3c-30.6 13.2-63.9 22.7-98.2 26.4a170.1 170.1 0 0 0 75-94 336.64 336.64 0 0 1-108.2 41.2A170.1 170.1 0 0 0 672 174c-94.5 0-170.5 76.6-170.5 170.6 0 13.2 1.6 26.4 4.2 39.1-141.5-7.4-267.7-75-351.6-178.5a169.32 169.32 0 0 0-23.2 86.1c0 59.2 30.1 111.4 76 142.1a172 172 0 0 1-77.1-21.7v2.1c0 82.9 58.6 151.6 136.7 167.4a180.6 180.6 0 0 1-44.9 5.8c-11.1 0-21.6-1.1-32.2-2.6C211 652 273.9 701.1 348.8 702.7c-58.6 45.9-132 72.9-211.7 72.9-14.3 0-27.5-.5-41.2-2.1C171.5 822 261.2 850 357.8 850 671.4 850 843 590.2 843 364.7c0-7.4 0-14.8-.5-22.2 33.2-24.3 62.3-54.4 85.5-88.2z"></path></svg>
                 </a>
                 <a class="footer__icon" href="https://github.com/great-expectations/great_expectations" target="_blank" rel="noreferrer noopener" aria-label="check out or Slack community">
-                  <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M511.6 76.3C264.3 76.2 64 276.4 64 523.5 64 718.9 189.3 885 363.8 946c23.5 5.9 19.9-10.8 19.9-22.2v-77.5c-135.7 15.9-141.2-73.9-150.3-88.9C215 726 171.5 718 184.5 703c30.9-15.9 62.4 4 98.9 57.9 26.4 39.1 77.9 32.5 104 26 5.7-23.5 17.9-44.5 34.7-60.8-140.6-25.2-199.2-111-199.2-213 0-49.5 16.3-95 48.3-131.7-20.4-60.5 1.9-112.3 4.9-120 58.1-5.2 118.5 41.6 123.2 45.3 33-8.9 70.7-13.6 112.9-13.6 42.4 0 80.2 4.9 113.5 13.9 11.3-8.6 67.3-48.8 121.3-43.9 2.9 7.7 24.7 58.3 5.5 118 32.4 36.8 48.9 82.7 48.9 132.3 0 102.2-59 188.1-200 212.9a127.5 127.5 0 0 1 38.1 91v112.5c.8 9 0 17.9 15 17.9 177.1-59.7 304.6-227 304.6-424.1 0-247.2-200.4-447.3-447.5-447.3z"></path></svg>                
+                  <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M511.6 76.3C264.3 76.2 64 276.4 64 523.5 64 718.9 189.3 885 363.8 946c23.5 5.9 19.9-10.8 19.9-22.2v-77.5c-135.7 15.9-141.2-73.9-150.3-88.9C215 726 171.5 718 184.5 703c30.9-15.9 62.4 4 98.9 57.9 26.4 39.1 77.9 32.5 104 26 5.7-23.5 17.9-44.5 34.7-60.8-140.6-25.2-199.2-111-199.2-213 0-49.5 16.3-95 48.3-131.7-20.4-60.5 1.9-112.3 4.9-120 58.1-5.2 118.5 41.6 123.2 45.3 33-8.9 70.7-13.6 112.9-13.6 42.4 0 80.2 4.9 113.5 13.9 11.3-8.6 67.3-48.8 121.3-43.9 2.9 7.7 24.7 58.3 5.5 118 32.4 36.8 48.9 82.7 48.9 132.3 0 102.2-59 188.1-200 212.9a127.5 127.5 0 0 1 38.1 91v112.5c.8 9 0 17.9 15 17.9 177.1-59.7 304.6-227 304.6-424.1 0-247.2-200.4-447.3-447.5-447.3z"></path></svg>
                 </a>
                 <a class="footer__icon" href="https://www.linkedin.com/company/superconductive-data" target="_blank" rel="noreferrer noopener" aria-label="check out or Slack community">
-                  <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M847.7 112H176.3c-35.5 0-64.3 28.8-64.3 64.3v671.4c0 35.5 28.8 64.3 64.3 64.3h671.4c35.5 0 64.3-28.8 64.3-64.3V176.3c0-35.5-28.8-64.3-64.3-64.3zm0 736c-447.8-.1-671.7-.2-671.7-.3.1-447.8.2-671.7.3-671.7 447.8.1 671.7.2 671.7.3-.1 447.8-.2 671.7-.3 671.7zM230.6 411.9h118.7v381.8H230.6zm59.4-52.2c37.9 0 68.8-30.8 68.8-68.8a68.8 68.8 0 1 0-137.6 0c-.1 38 30.7 68.8 68.8 68.8zm252.3 245.1c0-49.8 9.5-98 71.2-98 60.8 0 61.7 56.9 61.7 101.2v185.7h118.6V584.3c0-102.8-22.2-181.9-142.3-181.9-57.7 0-96.4 31.7-112.3 61.7h-1.6v-52.2H423.7v381.8h118.6V604.8z"></path></svg>                
+                  <svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 1024 1024" height="18px" width="18px" xmlns="http://www.w3.org/2000/svg"><path d="M847.7 112H176.3c-35.5 0-64.3 28.8-64.3 64.3v671.4c0 35.5 28.8 64.3 64.3 64.3h671.4c35.5 0 64.3-28.8 64.3-64.3V176.3c0-35.5-28.8-64.3-64.3-64.3zm0 736c-447.8-.1-671.7-.2-671.7-.3.1-447.8.2-671.7.3-671.7 447.8.1 671.7.2 671.7.3-.1 447.8-.2 671.7-.3 671.7zM230.6 411.9h118.7v381.8H230.6zm59.4-52.2c37.9 0 68.8-30.8 68.8-68.8a68.8 68.8 0 1 0-137.6 0c-.1 38 30.7 68.8 68.8 68.8zm252.3 245.1c0-49.8 9.5-98 71.2-98 60.8 0 61.7 56.9 61.7 101.2v185.7h118.6V584.3c0-102.8-22.2-181.9-142.3-181.9-57.7 0-96.4 31.7-112.3 61.7h-1.6v-52.2H423.7v381.8h118.6V604.8z"></path></svg>
                 </a>
               `,
             },

diff --git a/great_expectations/data_context/data_context/abstract_data_context.py b/great_expectations/data_context/data_context/abstract_data_context.py
@@ -164,12 +164,12 @@
 T = TypeVar("T", dict, list, str)
 
 
+@public_api
 class AbstractDataContext(ConfigPeer, ABC):
-    """
-    Base class for all DataContexts that contain all context-agnostic data context operations.
+    """Base class for all Data Contexts that contains shared functionality.
 
     The class encapsulates most store / core components and convenience methods used to access them, meaning the
-    majority of DataContext functionality lives here.
+    majority of Data Context functionality lives here.
     """
 
     # NOTE: <DataContextRefactor> These can become a property like ExpectationsStore.__name__ or placed in a separate

diff --git a/great_expectations/util.py b/great_expectations/util.py
@@ -55,6 +55,7 @@
 from pkg_resources import Distribution
 from typing_extensions import Literal, TypeGuard
 
+from great_expectations.core._docs_decorators import deprecated_argument, public_api
 from great_expectations.exceptions import (
     GXCloudConfigurationError,
     PluginClassNotFoundError,
@@ -1764,6 +1765,11 @@ def get_context(
     ...
 
 
+@public_api
+@deprecated_argument(argument_name="ge_cloud_base_url", version="0.15.37")
+@deprecated_argument(argument_name="ge_cloud_access_token", version="0.15.37")
+@deprecated_argument(argument_name="ge_cloud_organization_id", version="0.15.37")
+@deprecated_argument(argument_name="ge_cloud_mode", version="0.15.37")
 def get_context(
     project_config: Optional[Union[DataContextConfig, Mapping]] = None,
     context_root_dir: Optional[PathStr] = None,
@@ -1778,54 +1784,89 @@ def get_context(
     ge_cloud_organization_id: Optional[str] = None,
     ge_cloud_mode: Optional[bool] = None,
 ) -> AbstractDataContext:
-    """
-    Method to return the appropriate DataContext depending on parameters and environment.
+    """Method to return the appropriate Data Context depending on parameters and environment.
 
     Usage:
-        import great_expectations as gx
-        my_context = gx.get_context([parameters])
+        `import great_expectations as gx`
+
+        `my_context = gx.get_context(<insert_your_parameters>)`
+
+    This method returns the appropriate Data Context based on which parameters you've passed and / or your environment configuration:
+
+    - FileDataContext: Configuration stored in a file.
+
+    - EphemeralDataContext: Configuration passed in at runtime.
+
+    - CloudDataContext: Configuration stored in Great Expectations Cloud.
+
+    Read on for more details about each of the Data Context types:
+
+    **FileDataContext:** A Data Context configured via a yaml file. Returned by default if you have no cloud configuration set up and pass no parameters. If you pass context_root_dir, we will look for a great_expectations.yml configuration there. If not we will look at the following locations:
+
+    - Path defined in a GX_HOME environment variable.
+
+    - The current directory.
+
+    - Parent directories of the current directory (e.g. in case you invoke the CLI in a sub folder of your Great Expectations directory).
 
-    1. If gx.get_context() is run in a filesystem where `great_expectations init` has been run, then it will return a
-        FileDataContext.
+    Relevant parameters
 
-    2. If gx.get_context() is passed in a `context_root_dir` (which contains great_expectations.yml) then it will return
-         a FileDataContext.
+    - context_root_dir: Provide an alternative directory to look for GX config.
 
-    3. If gx.get_context() is passed in an in-memory `project_config` then it will return EphemeralDataContext.
-        `context_root_dir` can also be passed in, but the configurations from the in-memory config will override the
-        configurations in the `great_expectations.yml` file.
+    - project_config: Optionally override the configuration on disk - only if `context_root_dir` is also provided.
 
+    - runtime_environment: Optionally override specific configuration values.
 
-    4. If GX is being run in the Cloud, and the information needed for gx_cloud_config (ie gx_cloud_base_url,
-        gx_cloud_access_token, gx_cloud_organization_id) are passed in as parameters to get_context(), configured as
-        environment variables, or in a .conf file, then get_context() will return a CloudDataContext.
+    **EphemeralDataContext:** A temporary, in-memory Data Context typically used in a pipeline. The default if you pass in only a project_config and have no cloud configuration set up.
 
+    Relevant parameters
 
-    +-----------------------+---------------------+---------------+
-    |  get_context params   |    Env Not Config'd |  Env Config'd |
-    +-----------------------+---------------------+---------------+
-    | ()                    | Local               | Cloud         |
-    | (cloud_mode=True)     | Exception!          | Cloud         |
-    | (cloud_mode=False)    | Local               | Local         |
-    +-----------------------+---------------------+---------------+
+    - project_config: Used to configure the Data Context.
+
+    - runtime_environment: Optionally override specific configuration values.
+
+    **CloudDataContext:** A Data Context whose configuration comes from Great Expectations Cloud. The default if you have a cloud configuration set up. Pass `cloud_mode=False` if you have a cloud configuration set up and you do not wish to create a CloudDataContext.
+
+    Cloud configuration can be set up by passing `cloud_*` parameters to `get_context()`, configuring cloud environment variables, or in a great_expectations.conf file.
+
+    Relevant parameters
+
+    - cloud_base_url: Override env var or great_expectations.conf file.
+
+    - cloud_access_token: Override env var or great_expectations.conf file.
+
+    - cloud_organization_id: Override env var or great_expectations.conf file.
+
+    - cloud_mode: Set to True or False to explicitly enable/disable cloud mode.
+
+    - project_config: Optionally override the cloud configuration.
+
+    - runtime_environment: Optionally override specific configuration values.
 
     Args:
-        project_config (dict or DataContextConfig): In-memory configuration for DataContext.
+        project_config: In-memory configuration for Data Context.
         context_root_dir (str or pathlib.Path): Path to directory that contains great_expectations.yml file
-        runtime_environment (dict): A dictionary of values can be passed to a DataContext when it is instantiated.
+        runtime_environment: A dictionary of values can be passed to a DataContext when it is instantiated.
             These values will override both values from the config variables file and
             from environment variables.
-
-        The following parameters are relevant when running ge_cloud
-            * cloud_base_url (str): url for GX Cloud endpoint.
-            * cloud_access_token (str): access_token for GX Cloud account.
-            * cloud_organization_id (str): org_id for GX Cloud account.
-            * cloud_mode (bool): bool flag to specify whether to run GX in Cloud mode (default is None).
+        cloud_base_url: url for GX Cloud endpoint.
+        cloud_access_token: access_token for GX Cloud account.
+        cloud_organization_id: org_id for GX Cloud account.
+        cloud_mode: whether to run GX in Cloud mode (default is None).
+            If None, cloud mode is assumed if cloud credentials are set up. Set to False to override.
+        ge_cloud_base_url: url for GX Cloud endpoint.
+        ge_cloud_access_token: access_token for GX Cloud account.
+        ge_cloud_organization_id: org_id for GX Cloud account.
+        ge_cloud_mode: whether to run GX in Cloud mode (default is None).
+            If None, cloud mode is assumed if cloud credentials are set up. Set to False to override.
 
     Returns:
-        DataContext. Either a FileDataContext, EpehemralDataContext, or CloudDataContext depending on environment and/or
-        parameters
+        A Data Context. Either a FileDataContext, EphemeralDataContext, or
+        CloudDataContext depending on environment and/or
+        parameters.
 
+    Raises:
+        GXCloudConfigurationError: Cloud mode enabled, but missing configuration.
     """
     from great_expectations.data_context.data_context import (
         CloudDataContext,

diff --git a/src/css/api_docs/basic-modified.scss b/src/css/api_docs/basic-modified.scss
@@ -621,7 +621,9 @@ dl.field-list > dt {
 }
 
 dl.field-list > dt:after {
-    content: ":";
+    // Note: colon in content removed since it was duplicating
+    // on Netlify deploy.
+    content: "";
 }
 
 dl.field-list > dd {