From 6ccd535dc65895bdf8a92cc1cb855f14b6656cdf Mon Sep 17 00:00:00 2001 From: Scott Beddall <45376673+scbedd@users.noreply.github.com> Date: Tue, 4 Apr 2023 10:57:09 -0700 Subject: [PATCH] Rename `api-stub-generator` to `apiview-stub-generator` (#5899) --- .../stages/archetype-sdk-tool-python.yml | 2 +- eng/scripts/python_sdk_report.py | 2 +- eng/scripts/python_version_check.py | 2 +- .../CHANGELOG.md | 0 .../MANIFEST.in | 0 .../README.md | 4 +- .../apistub/__init__.py | 2 +- .../apistub/__main__.py | 0 .../apistub/_apiview.py | 4 +- .../apistub/_diagnostic.py | 0 .../apistub/_metadata_map.py | 0 .../apistub/_node_index.py | 0 .../apistub/_stub_generator.py | 0 .../apistub/_token.py | 0 .../apistub/_token_kind.py | 0 .../apistub/_version.py | 0 .../apistub/nodes/__init__.py | 0 .../apistub/nodes/_annotation_parser.py | 0 .../apistub/nodes/_argtype.py | 0 .../apistub/nodes/_astroid_parser.py | 0 .../apistub/nodes/_base_node.py | 0 .../apistub/nodes/_class_node.py | 0 .../apistub/nodes/_data_class_node.py | 0 .../apistub/nodes/_docstring_parser.py | 0 .../apistub/nodes/_enum_node.py | 0 .../apistub/nodes/_function_node.py | 0 .../apistub/nodes/_key_node.py | 0 .../apistub/nodes/_module_node.py | 0 .../apistub/nodes/_property_node.py | 0 .../apistub/nodes/_pylint_parser.py | 0 .../apistub/nodes/_variable_node.py | 0 .../apistub/pylintrc | 0 .../apistubgen.py | 0 .../apiview_reqs.txt | 0 .../ci.yml | 8 +- .../dev_requirements.txt | 0 .../setup.py | 2 +- .../tests/__init__.py | 0 .../tests/_test_util.py | 0 .../tests/apiview_test.py | 0 .../tests/class_parsing_test.py | 0 .../tests/dataclass_parsing_test.py | 0 .../tests/docstring_parser_test.py | 0 .../tests/function_parsing_test.py | 0 .../tox.ini | 0 .../APIView/APIViewWeb/APIViewWeb.csproj | 2 +- src/dotnet/APIView/APIViewWeb/CONTRIBUTING.md | 390 +++++++++--------- 47 files changed, 209 insertions(+), 209 deletions(-) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/CHANGELOG.md (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/MANIFEST.in (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/README.md (87%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/__init__.py (93%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/__main__.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_apiview.py (98%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_diagnostic.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_metadata_map.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_node_index.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_stub_generator.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_token.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_token_kind.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/_version.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/__init__.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_annotation_parser.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_argtype.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_astroid_parser.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_base_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_class_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_data_class_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_docstring_parser.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_enum_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_function_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_key_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_module_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_property_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_pylint_parser.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/nodes/_variable_node.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistub/pylintrc (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apistubgen.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/apiview_reqs.txt (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/ci.yml (82%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/dev_requirements.txt (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/setup.py (97%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/__init__.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/_test_util.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/apiview_test.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/class_parsing_test.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/dataclass_parsing_test.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/docstring_parser_test.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tests/function_parsing_test.py (100%) rename packages/python-packages/{api-stub-generator => apiview-stub-generator}/tox.ini (100%) diff --git a/eng/pipelines/templates/stages/archetype-sdk-tool-python.yml b/eng/pipelines/templates/stages/archetype-sdk-tool-python.yml index 085e981b7..039cf93a4 100644 --- a/eng/pipelines/templates/stages/archetype-sdk-tool-python.yml +++ b/eng/pipelines/templates/stages/archetype-sdk-tool-python.yml @@ -41,7 +41,7 @@ stages: displayName: 'Setup Python Environment' - pwsh: | - Write-Host "Bundling stable version of python api-stub-generator" + Write-Host "Bundling stable version of python apiview-stub-generator" python setup.py bdist_wheel --universal --dist-dir $(Build.ArtifactStagingDirectory) displayName: 'Build ${{ parameters.PackageName }}' workingDirectory: $(Build.SourcesDirectory)/${{ parameters.PackagePath }} diff --git a/eng/scripts/python_sdk_report.py b/eng/scripts/python_sdk_report.py index a2a8043e4..af4dc3502 100644 --- a/eng/scripts/python_sdk_report.py +++ b/eng/scripts/python_sdk_report.py @@ -36,7 +36,7 @@ if __name__ == '__main__': warning_color = '\033[91m' end_color = '\033[0m' - stub_gen_path = os.path.join(ROOT, 'packages', 'python-packages', 'api-stub-generator') + stub_gen_path = os.path.join(ROOT, 'packages', 'python-packages', 'apiview-stub-generator') changelog_path = os.path.join(stub_gen_path, "CHANGELOG.md") version_path = os.path.join(stub_gen_path, 'apistub', '_version.py') diff --git a/eng/scripts/python_version_check.py b/eng/scripts/python_version_check.py index 87115d438..938d0e1fb 100644 --- a/eng/scripts/python_version_check.py +++ b/eng/scripts/python_version_check.py @@ -20,7 +20,7 @@ if __name__ == '__main__': warning_color = '\033[91m' end_color = '\033[0m' - stub_gen_path = os.path.join(ROOT, 'packages', 'python-packages', 'api-stub-generator') + stub_gen_path = os.path.join(ROOT, 'packages', 'python-packages', 'apiview-stub-generator') changelog_path = os.path.join(stub_gen_path, "CHANGELOG.md") version_path = os.path.join(stub_gen_path, 'apistub', '_version.py') diff --git a/packages/python-packages/api-stub-generator/CHANGELOG.md b/packages/python-packages/apiview-stub-generator/CHANGELOG.md similarity index 100% rename from packages/python-packages/api-stub-generator/CHANGELOG.md rename to packages/python-packages/apiview-stub-generator/CHANGELOG.md diff --git a/packages/python-packages/api-stub-generator/MANIFEST.in b/packages/python-packages/apiview-stub-generator/MANIFEST.in similarity index 100% rename from packages/python-packages/api-stub-generator/MANIFEST.in rename to packages/python-packages/apiview-stub-generator/MANIFEST.in diff --git a/packages/python-packages/api-stub-generator/README.md b/packages/python-packages/apiview-stub-generator/README.md similarity index 87% rename from packages/python-packages/api-stub-generator/README.md rename to packages/python-packages/apiview-stub-generator/README.md index fe0b4b0c2..c49be9834 100644 --- a/packages/python-packages/api-stub-generator/README.md +++ b/packages/python-packages/apiview-stub-generator/README.md @@ -14,9 +14,9 @@ Following are the steps to create an API review request for python package. 2. Upload stub file tokens into API review portal ### Generate stub File -`api-stub-generator` package is used to generate stub file tokens from either source code repo or from prebuilt wheel package. Following are the steps to generate stub file token. +`apiview-stub-generator` package is used to generate stub file tokens from either source code repo or from prebuilt wheel package. Following are the steps to generate stub file token. -Install `api-stub-generator` package. From the root of the api-stub-generator package, run: +Install `apiview-stub-generator` package. From the root of the apiview-stub-generator package, run: ``` pip install . --extra-index-url="https://pkgs.dev.azure.com/azure-sdk/public/_packaging/azure-sdk-for-python/pypi/simple/" ``` diff --git a/packages/python-packages/api-stub-generator/apistub/__init__.py b/packages/python-packages/apiview-stub-generator/apistub/__init__.py similarity index 93% rename from packages/python-packages/api-stub-generator/apistub/__init__.py rename to packages/python-packages/apiview-stub-generator/apistub/__init__.py index 45c89b386..dd7fc45b8 100644 --- a/packages/python-packages/api-stub-generator/apistub/__init__.py +++ b/packages/python-packages/apiview-stub-generator/apistub/__init__.py @@ -23,7 +23,7 @@ __all__ = [ def console_entry_point(): - print("Running api-stub-generator version {}".format(__version__)) + print("Running apiview-stub-generator version {}".format(__version__)) stub_generator = StubGenerator() apiview = stub_generator.generate_tokens() json_tokens = stub_generator.serialize(apiview) diff --git a/packages/python-packages/api-stub-generator/apistub/__main__.py b/packages/python-packages/apiview-stub-generator/apistub/__main__.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/__main__.py rename to packages/python-packages/apiview-stub-generator/apistub/__main__.py diff --git a/packages/python-packages/api-stub-generator/apistub/_apiview.py b/packages/python-packages/apiview-stub-generator/apistub/_apiview.py similarity index 98% rename from packages/python-packages/api-stub-generator/apistub/_apiview.py rename to packages/python-packages/apiview-stub-generator/apistub/_apiview.py index 9432f7ba5..8533d8f9a 100644 --- a/packages/python-packages/api-stub-generator/apistub/_apiview.py +++ b/packages/python-packages/apiview-stub-generator/apistub/_apiview.py @@ -13,7 +13,7 @@ from ._metadata_map import MetadataMap JSON_FIELDS = ["Name", "Version", "VersionString", "Navigation", "Tokens", "Diagnostics", "PackageName", "Language"] -HEADER_TEXT = "# Package is parsed using api-stub-generator(version:{0}), Python version: {1}".format(VERSION, platform.python_version()) +HEADER_TEXT = "# Package is parsed using apiview-stub-generator(version:{0}), Python version: {1}".format(VERSION, platform.python_version()) TYPE_NAME_REGEX = re.compile(r"(~?[a-zA-Z\d._]+)") TYPE_OR_SEPARATOR = " or " @@ -28,7 +28,7 @@ class ApiView: @classmethod def get_root_path(cls): - """ Looks for the root of the api-stub-generator package. + """ Looks for the root of the apiview-stub-generator package. """ path = os.path.abspath(os.path.join(os.path.dirname(__file__))) while os.path.split(path)[1]: diff --git a/packages/python-packages/api-stub-generator/apistub/_diagnostic.py b/packages/python-packages/apiview-stub-generator/apistub/_diagnostic.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_diagnostic.py rename to packages/python-packages/apiview-stub-generator/apistub/_diagnostic.py diff --git a/packages/python-packages/api-stub-generator/apistub/_metadata_map.py b/packages/python-packages/apiview-stub-generator/apistub/_metadata_map.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_metadata_map.py rename to packages/python-packages/apiview-stub-generator/apistub/_metadata_map.py diff --git a/packages/python-packages/api-stub-generator/apistub/_node_index.py b/packages/python-packages/apiview-stub-generator/apistub/_node_index.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_node_index.py rename to packages/python-packages/apiview-stub-generator/apistub/_node_index.py diff --git a/packages/python-packages/api-stub-generator/apistub/_stub_generator.py b/packages/python-packages/apiview-stub-generator/apistub/_stub_generator.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_stub_generator.py rename to packages/python-packages/apiview-stub-generator/apistub/_stub_generator.py diff --git a/packages/python-packages/api-stub-generator/apistub/_token.py b/packages/python-packages/apiview-stub-generator/apistub/_token.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_token.py rename to packages/python-packages/apiview-stub-generator/apistub/_token.py diff --git a/packages/python-packages/api-stub-generator/apistub/_token_kind.py b/packages/python-packages/apiview-stub-generator/apistub/_token_kind.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_token_kind.py rename to packages/python-packages/apiview-stub-generator/apistub/_token_kind.py diff --git a/packages/python-packages/api-stub-generator/apistub/_version.py b/packages/python-packages/apiview-stub-generator/apistub/_version.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/_version.py rename to packages/python-packages/apiview-stub-generator/apistub/_version.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/__init__.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/__init__.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/__init__.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/__init__.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_annotation_parser.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_annotation_parser.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_annotation_parser.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_annotation_parser.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_argtype.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_argtype.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_argtype.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_argtype.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_astroid_parser.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_astroid_parser.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_astroid_parser.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_astroid_parser.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_base_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_base_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_base_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_base_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_class_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_class_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_class_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_class_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_data_class_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_data_class_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_data_class_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_data_class_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_docstring_parser.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_docstring_parser.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_docstring_parser.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_docstring_parser.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_enum_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_enum_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_enum_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_enum_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_function_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_function_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_function_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_function_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_key_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_key_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_key_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_key_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_module_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_module_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_module_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_module_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_property_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_property_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_property_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_property_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_pylint_parser.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_pylint_parser.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_pylint_parser.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_pylint_parser.py diff --git a/packages/python-packages/api-stub-generator/apistub/nodes/_variable_node.py b/packages/python-packages/apiview-stub-generator/apistub/nodes/_variable_node.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/nodes/_variable_node.py rename to packages/python-packages/apiview-stub-generator/apistub/nodes/_variable_node.py diff --git a/packages/python-packages/api-stub-generator/apistub/pylintrc b/packages/python-packages/apiview-stub-generator/apistub/pylintrc similarity index 100% rename from packages/python-packages/api-stub-generator/apistub/pylintrc rename to packages/python-packages/apiview-stub-generator/apistub/pylintrc diff --git a/packages/python-packages/api-stub-generator/apistubgen.py b/packages/python-packages/apiview-stub-generator/apistubgen.py similarity index 100% rename from packages/python-packages/api-stub-generator/apistubgen.py rename to packages/python-packages/apiview-stub-generator/apistubgen.py diff --git a/packages/python-packages/api-stub-generator/apiview_reqs.txt b/packages/python-packages/apiview-stub-generator/apiview_reqs.txt similarity index 100% rename from packages/python-packages/api-stub-generator/apiview_reqs.txt rename to packages/python-packages/apiview-stub-generator/apiview_reqs.txt diff --git a/packages/python-packages/api-stub-generator/ci.yml b/packages/python-packages/apiview-stub-generator/ci.yml similarity index 82% rename from packages/python-packages/api-stub-generator/ci.yml rename to packages/python-packages/apiview-stub-generator/ci.yml index f66b3aa50..1b54d96eb 100644 --- a/packages/python-packages/api-stub-generator/ci.yml +++ b/packages/python-packages/apiview-stub-generator/ci.yml @@ -8,7 +8,7 @@ trigger: - hotfix/* paths: include: - - packages/python-packages/api-stub-generator + - packages/python-packages/apiview-stub-generator pr: branches: @@ -19,13 +19,13 @@ pr: - hotfix/* paths: include: - - packages/python-packages/api-stub-generator + - packages/python-packages/apiview-stub-generator extends: template: /eng/pipelines/templates/stages/archetype-sdk-tool-python.yml parameters: PythonVersion: '3.10' - PackagePath: 'packages/python-packages/api-stub-generator' + PackagePath: 'packages/python-packages/apiview-stub-generator' FeedName: 'public/azure-sdk-for-python' ArtifactName: 'apiviewparserpython' PackageName: 'Python API View Parser' @@ -35,7 +35,7 @@ extends: displayName: 'Verify Python APIView version consistency' - script: | - cd $(Build.SourcesDirectory)/packages/python-packages/api-stub-generator + cd $(Build.SourcesDirectory)/packages/python-packages/apiview-stub-generator python -m pip install tox tox -e pytest,stubgen displayName: Run APIView tests diff --git a/packages/python-packages/api-stub-generator/dev_requirements.txt b/packages/python-packages/apiview-stub-generator/dev_requirements.txt similarity index 100% rename from packages/python-packages/api-stub-generator/dev_requirements.txt rename to packages/python-packages/apiview-stub-generator/dev_requirements.txt diff --git a/packages/python-packages/api-stub-generator/setup.py b/packages/python-packages/apiview-stub-generator/setup.py similarity index 97% rename from packages/python-packages/api-stub-generator/setup.py rename to packages/python-packages/apiview-stub-generator/setup.py index feacff63c..5bf9c4898 100644 --- a/packages/python-packages/api-stub-generator/setup.py +++ b/packages/python-packages/apiview-stub-generator/setup.py @@ -1,7 +1,7 @@ from setuptools import setup, find_packages import os, re -PACKAGE_NAME = "api-stub-generator" +PACKAGE_NAME = "apiview-stub-generator" DESCRIPTION = ( "A stub generator for published APIs, variables and properties in a package" diff --git a/packages/python-packages/api-stub-generator/tests/__init__.py b/packages/python-packages/apiview-stub-generator/tests/__init__.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/__init__.py rename to packages/python-packages/apiview-stub-generator/tests/__init__.py diff --git a/packages/python-packages/api-stub-generator/tests/_test_util.py b/packages/python-packages/apiview-stub-generator/tests/_test_util.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/_test_util.py rename to packages/python-packages/apiview-stub-generator/tests/_test_util.py diff --git a/packages/python-packages/api-stub-generator/tests/apiview_test.py b/packages/python-packages/apiview-stub-generator/tests/apiview_test.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/apiview_test.py rename to packages/python-packages/apiview-stub-generator/tests/apiview_test.py diff --git a/packages/python-packages/api-stub-generator/tests/class_parsing_test.py b/packages/python-packages/apiview-stub-generator/tests/class_parsing_test.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/class_parsing_test.py rename to packages/python-packages/apiview-stub-generator/tests/class_parsing_test.py diff --git a/packages/python-packages/api-stub-generator/tests/dataclass_parsing_test.py b/packages/python-packages/apiview-stub-generator/tests/dataclass_parsing_test.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/dataclass_parsing_test.py rename to packages/python-packages/apiview-stub-generator/tests/dataclass_parsing_test.py diff --git a/packages/python-packages/api-stub-generator/tests/docstring_parser_test.py b/packages/python-packages/apiview-stub-generator/tests/docstring_parser_test.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/docstring_parser_test.py rename to packages/python-packages/apiview-stub-generator/tests/docstring_parser_test.py diff --git a/packages/python-packages/api-stub-generator/tests/function_parsing_test.py b/packages/python-packages/apiview-stub-generator/tests/function_parsing_test.py similarity index 100% rename from packages/python-packages/api-stub-generator/tests/function_parsing_test.py rename to packages/python-packages/apiview-stub-generator/tests/function_parsing_test.py diff --git a/packages/python-packages/api-stub-generator/tox.ini b/packages/python-packages/apiview-stub-generator/tox.ini similarity index 100% rename from packages/python-packages/api-stub-generator/tox.ini rename to packages/python-packages/apiview-stub-generator/tox.ini diff --git a/src/dotnet/APIView/APIViewWeb/APIViewWeb.csproj b/src/dotnet/APIView/APIViewWeb/APIViewWeb.csproj index 9653c108b..fa61e7d4a 100644 --- a/src/dotnet/APIView/APIViewWeb/APIViewWeb.csproj +++ b/src/dotnet/APIView/APIViewWeb/APIViewWeb.csproj @@ -7,7 +7,7 @@ 79cceff6-d533-4370-a0ee-f3321a343907 true ..\..\..\java\apiview-java-processor\target\apiview-java-processor-1.28.0.jar - ..\..\..\..\packages\python-packages\api-stub-generator\dist\api_stub_generator-0.1.0-py3-none-any.whl + ..\..\..\..\packages\python-packages\apiview-stub-generator\dist\api_stub_generator-0.1.0-py3-none-any.whl ..\..\..\go\apiviewgo.exe ..\..\..\..\tools\apiview\parsers\js-api-parser\ latest diff --git a/src/dotnet/APIView/APIViewWeb/CONTRIBUTING.md b/src/dotnet/APIView/APIViewWeb/CONTRIBUTING.md index d4a2e337c..fe5951aed 100644 --- a/src/dotnet/APIView/APIViewWeb/CONTRIBUTING.md +++ b/src/dotnet/APIView/APIViewWeb/CONTRIBUTING.md @@ -1,196 +1,196 @@ -# Contributing - -This project welcomes contributions and suggestions. Most contributions require you to agree to a -Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us -the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. - -When you submit a pull request, a CLA bot will automatically determine whether you need to provide -a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions -provided by the bot. You will only need to do this once across all repos using our CLA. - -This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). -For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or -contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. - -## Where to begin - -Core of the APIView tool is the web app developed using ASP.Net and TypeScript. This core module takes care of presenting reviews to users, storing review files and metadata in Azure Storage Account and Cosmos database and process requests from Azure Devops pipelines and respond. We also have language level parsers that converts each language specific artifact into a common json stub file that's known to core APIView web app. So, first step as a contributor is to understand the feature or bug fix you would like to submit and identify the area you would like to contribute to. Language parsers are either added as plugin modules developed in .Net or developed using corresponding language as command line tool to extract and generate stub file. If change is specific to a language in how langauge specific API details are extracted to stub tokens then change will be at parser level for that language. If change is applicable for all languages then change will most likely be in core APIView web app. - - -| Module | Source Path | -|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------| -| apiview.dev | https://github.com/Azure/azure-sdk-tools/tree/main/src/dotnet/APIView/APIViewWeb | -| C# | https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIView/Languages/CodeFileBuilder.cs | -| C | https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/Languages/CLanguageService.cs | -| C++ | https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/Languages/CppLanguageService.cs | -| Java | https://github.com/Azure/azure-sdk-tools/tree/main/src/java/apiview-java-processor | -| JS/TS | https://github.com/Azure/azure-sdk-tools/tree/main/tools/apiview/parsers/js-api-parser | -| Python | https://github.com/Azure/azure-sdk-tools/tree/main/packages/python-packages/api-stub-generator | -| Go | https://github.com/Azure/azure-sdk-tools/tree/main/src/go | -| Swift | https://github.com/Azure/azure-sdk-tools/tree/main/src/swift | - - - -## Pre-requisites - -### Development machine setup - -Following are tools required to develop and run test instance of APIView to verify changes locally on your machine. - -- Git -- Visual Studio -- .Net -- Any LTS version of Node.js [download](https://nodejs.org/en/download/) -- Java (Optional: Only required if you want to generate Java review locally) -- Python 3.9+ (Optional: Only required if you want to generate Python review locally) -- Go compiler (Optional: Only to generate and test Go reviews) -- Xcode 10.2 or higher (Optional: Only to generate and test Go reviews) - - Azure subscription with permission to create storage account and Cosmos DB instance. - -In addition to local machine setup, you will also require an Azure storage account to store source and stub file and Azure Cosmos database instance to store review metadata. We have added a section below with more details on Azure resources required for testing. - - -### Azure resources required to run APIView instance locally - -You can verify your code changes locally by running a debugging instance of APIView tool locally using visual studio. This still requires Azure storage blob and Azure Cosmos DB instance to store stub file and metadata. Local development and testing do not require any Azure web app instance. - -Create following Azure resources in your Azure subscription. - -#### Azure storage account - - - Create a storage account in Azure. [Azure storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal) - - Create three blob storage containers with names as follows within the storage account created in previous step: `originals`, `codefiles`, and `usagesamples` - -#### Azure Cosmos DB - - Create a Cosmos DB account in Azure and then create a database with name `APIView` in this account. Once database is created successfully then create three containers in `APIView` database. Following are the list of containers and partition key for each of them. Partition key is case sensitive. - - | Container Name | Partition Key | - |---------------------|--------------------| - | Reviews | /id | - | Comments | /ReviewId | - | PullRequests | /PullRequestNumber | - | UsageSamples | /ReviewId | +# Contributing + +This project welcomes contributions and suggestions. Most contributions require you to agree to a +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. + +When you submit a pull request, a CLA bot will automatically determine whether you need to provide +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions +provided by the bot. You will only need to do this once across all repos using our CLA. + +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. + +## Where to begin + +Core of the APIView tool is the web app developed using ASP.Net and TypeScript. This core module takes care of presenting reviews to users, storing review files and metadata in Azure Storage Account and Cosmos database and process requests from Azure Devops pipelines and respond. We also have language level parsers that converts each language specific artifact into a common json stub file that's known to core APIView web app. So, first step as a contributor is to understand the feature or bug fix you would like to submit and identify the area you would like to contribute to. Language parsers are either added as plugin modules developed in .Net or developed using corresponding language as command line tool to extract and generate stub file. If change is specific to a language in how langauge specific API details are extracted to stub tokens then change will be at parser level for that language. If change is applicable for all languages then change will most likely be in core APIView web app. + + +| Module | Source Path | +|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------| +| apiview.dev | https://github.com/Azure/azure-sdk-tools/tree/main/src/dotnet/APIView/APIViewWeb | +| C# | https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIView/Languages/CodeFileBuilder.cs | +| C | https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/Languages/CLanguageService.cs | +| C++ | https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/Languages/CppLanguageService.cs | +| Java | https://github.com/Azure/azure-sdk-tools/tree/main/src/java/apiview-java-processor | +| JS/TS | https://github.com/Azure/azure-sdk-tools/tree/main/tools/apiview/parsers/js-api-parser | +| Python | https://github.com/Azure/azure-sdk-tools/tree/main/packages/python-packages/apiview-stub-generator | +| Go | https://github.com/Azure/azure-sdk-tools/tree/main/src/go | +| Swift | https://github.com/Azure/azure-sdk-tools/tree/main/src/swift | + + + +## Pre-requisites + +### Development machine setup + +Following are tools required to develop and run test instance of APIView to verify changes locally on your machine. + +- Git +- Visual Studio +- .Net +- Any LTS version of Node.js [download](https://nodejs.org/en/download/) +- Java (Optional: Only required if you want to generate Java review locally) +- Python 3.9+ (Optional: Only required if you want to generate Python review locally) +- Go compiler (Optional: Only to generate and test Go reviews) +- Xcode 10.2 or higher (Optional: Only to generate and test Go reviews) + - Azure subscription with permission to create storage account and Cosmos DB instance. + +In addition to local machine setup, you will also require an Azure storage account to store source and stub file and Azure Cosmos database instance to store review metadata. We have added a section below with more details on Azure resources required for testing. + + +### Azure resources required to run APIView instance locally + +You can verify your code changes locally by running a debugging instance of APIView tool locally using visual studio. This still requires Azure storage blob and Azure Cosmos DB instance to store stub file and metadata. Local development and testing do not require any Azure web app instance. + +Create following Azure resources in your Azure subscription. + +#### Azure storage account + + - Create a storage account in Azure. [Azure storage account](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal) + - Create three blob storage containers with names as follows within the storage account created in previous step: `originals`, `codefiles`, and `usagesamples` + +#### Azure Cosmos DB + - Create a Cosmos DB account in Azure and then create a database with name `APIView` in this account. Once database is created successfully then create three containers in `APIView` database. Following are the list of containers and partition key for each of them. Partition key is case sensitive. + + | Container Name | Partition Key | + |---------------------|--------------------| + | Reviews | /id | + | Comments | /ReviewId | + | PullRequests | /PullRequestNumber | + | UsageSamples | /ReviewId | | UserPreference | /UserName | - | Profiles | /id | - - - -## Getting Started - -### Create a GitHub Oath application for local authentication -- Go to `github.com/` -- Go to `Settings` -> `Developer Settings` -- Select `OAuth Apps` from menu options -- Click on `New OAuth App` -- Give an application name, for e.g. APIViewDebug and URL `http://localhost:5000`. Add same URL as call back URL also. -- Copy Client ID and Secret for this OAuth app. These are required to be added in configuration to run local debugging instance. - - -### Clone source code repo -- Create a new fork of GitHub repo [azure-sdk-tools](https://github.com/Azure/azure-sdk-tools) -- Clone forked repo to development machine. -- Create a new branch from `main` branch of cloned source repo. - - -### Setup debugging instance using Visual Studio -- If you are making any changes to apiview core web app or any of the languages that are integrated within core web app (C, C++, C#) or to test APIVIew locally then open `Visual Studio` and load `", - "ClientSecret": "" - }, - "Blob": { - "ConnectionString": "" - }, - "Cosmos": { - "ConnectionString": "" - }, - "github-access-token": "", - "ApiKey": "", - "PYTHONEXECUTABLEPATH": "", - "BackgroundTaskDisabled": true - } - -### Compile TypeScript code - -APIView web app has some type script code and this needs to be compiled for client side processing. Following are the steps to compile typescript code before starting to debug APIView. - -- Go to `/Client` -- run `npm install` -- run `npm run-script build` - -This should compile and get client-side scripting as well as CSS ready. - - -### Verify setup - -Okay. I have followed all the steps and now I need to verify if it's running fine locally to debug APIView. Download a NuGet file from NuGet package manager for any Azure package to test uploading to API review. One of the options is Azure.Template package [here](https://www.nuget.org/packages/Azure.Template/) - -- Select `APIViewWeb` from solution explorer in Visual Studio and run debug or right click and select `Debug` -> `Start New Instance` - -- This should open a browser instance with login page to APIView. Click on the Login and this should ask your GitHub credentials and a confirmation to allow OAuth application created earlier to access your GitHub public information. - -- If GitHub Client ID configuration in manage user secrets is correct, login should be successful if you are part of Azure or Microsoft GitHub org and org information is publicly available under your GitHub account. - -- Home page should be displayed with an empty list of reviews. - -- Click `Create review` button and upload previously downloaded `Azure.Template` package. It should show API review for Azure.Template if everything is setup correctly. - - -If any of the above steps is showing errors, following are the items to check: - -- Verify OAuth Client ID and Secret - -- Verify blob connection string and Cosmos DB connection string - -- Verify and ensure storage account has two containers as mentioned above - -- Verify and ensure cosmos DB instance has all 3 containers as per the instructions above and verify partition key for each of them. - - -Happy coding!!!! - - - -## I have made my changes. what's next? - - If change is in core apiview web app module then start a debug run using Visual Studio and verify the change using an existing review as well as by creating a new review. - - If change is specific to a language parser, then follow language specific parser testing guidelines. - - #### C, C++, C# - - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) - - #### Python - - Install python api stub generator package using Python version configured in `PYTHONEXECUTABLEPATH` - - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) - - #### Java - - Build Java package parser jar file and copy the jar file to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/ - - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) - - #### Go - - Compile and build Go source parser into .exe file and copy the .exe file to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/ - - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) - - #### JS/TS - - Got to /tools/apiview/parsers/js-api-parser - - run `npm install` - - run `npm run-script build` - - Copy compiled `export.js` to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/ - - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) - - - Parser version should always be incremented if change is at parser level and if that change is required to be reflected on existing reviews as well. Existing reviews are refreshed to reflect the changes as a backend task if parser version is changed. So, this won't reflect immediately. - - Create a GitHub pull request for the changes to merge it to main branch if code changes are ready and tested thoroughly. - + | Profiles | /id | + + + +## Getting Started + +### Create a GitHub Oath application for local authentication +- Go to `github.com/` +- Go to `Settings` -> `Developer Settings` +- Select `OAuth Apps` from menu options +- Click on `New OAuth App` +- Give an application name, for e.g. APIViewDebug and URL `http://localhost:5000`. Add same URL as call back URL also. +- Copy Client ID and Secret for this OAuth app. These are required to be added in configuration to run local debugging instance. + + +### Clone source code repo +- Create a new fork of GitHub repo [azure-sdk-tools](https://github.com/Azure/azure-sdk-tools) +- Clone forked repo to development machine. +- Create a new branch from `main` branch of cloned source repo. + + +### Setup debugging instance using Visual Studio +- If you are making any changes to apiview core web app or any of the languages that are integrated within core web app (C, C++, C#) or to test APIVIew locally then open `Visual Studio` and load `", + "ClientSecret": "" + }, + "Blob": { + "ConnectionString": "" + }, + "Cosmos": { + "ConnectionString": "" + }, + "github-access-token": "", + "ApiKey": "", + "PYTHONEXECUTABLEPATH": "", + "BackgroundTaskDisabled": true + } + +### Compile TypeScript code + +APIView web app has some type script code and this needs to be compiled for client side processing. Following are the steps to compile typescript code before starting to debug APIView. + +- Go to `/Client` +- run `npm install` +- run `npm run-script build` + +This should compile and get client-side scripting as well as CSS ready. + + +### Verify setup + +Okay. I have followed all the steps and now I need to verify if it's running fine locally to debug APIView. Download a NuGet file from NuGet package manager for any Azure package to test uploading to API review. One of the options is Azure.Template package [here](https://www.nuget.org/packages/Azure.Template/) + +- Select `APIViewWeb` from solution explorer in Visual Studio and run debug or right click and select `Debug` -> `Start New Instance` + +- This should open a browser instance with login page to APIView. Click on the Login and this should ask your GitHub credentials and a confirmation to allow OAuth application created earlier to access your GitHub public information. + +- If GitHub Client ID configuration in manage user secrets is correct, login should be successful if you are part of Azure or Microsoft GitHub org and org information is publicly available under your GitHub account. + +- Home page should be displayed with an empty list of reviews. + +- Click `Create review` button and upload previously downloaded `Azure.Template` package. It should show API review for Azure.Template if everything is setup correctly. + + +If any of the above steps is showing errors, following are the items to check: + +- Verify OAuth Client ID and Secret + +- Verify blob connection string and Cosmos DB connection string + +- Verify and ensure storage account has two containers as mentioned above + +- Verify and ensure cosmos DB instance has all 3 containers as per the instructions above and verify partition key for each of them. + + +Happy coding!!!! + + + +## I have made my changes. what's next? + + If change is in core apiview web app module then start a debug run using Visual Studio and verify the change using an existing review as well as by creating a new review. + + If change is specific to a language parser, then follow language specific parser testing guidelines. + + #### C, C++, C# + - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) + + #### Python + - Install python api stub generator package using Python version configured in `PYTHONEXECUTABLEPATH` + - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) + + #### Java + - Build Java package parser jar file and copy the jar file to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/ + - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) + + #### Go + - Compile and build Go source parser into .exe file and copy the .exe file to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/ + - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) + + #### JS/TS + - Got to /tools/apiview/parsers/js-api-parser + - run `npm install` + - run `npm run-script build` + - Copy compiled `export.js` to following location within local code repo /artifacts/bin/APIVIewWeb/Debug/<.NetVersion>/ + - Start Visual Studio debug run and create a new review as per the instructions in [APIView README.md](https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/APIViewWeb/README.md) + + + Parser version should always be incremented if change is at parser level and if that change is required to be reflected on existing reviews as well. Existing reviews are refreshed to reflect the changes as a backend task if parser version is changed. So, this won't reflect immediately. + + Create a GitHub pull request for the changes to merge it to main branch if code changes are ready and tested thoroughly. +