{
    "info": {
        "author": "Microsoft Corporation",
        "author_email": "azuresdkengsysadmins@microsoft.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 3 - Alpha",
            "License :: OSI Approved :: MIT License",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.4",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7"
        ],
        "description": "# Doc Warden [![Build Status](https://dev.azure.com/azure-sdk/public/_apis/build/status/108?branchName=master)](https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=108&branchName=master)\n\nEvery CI build owned by the Azure-SDK team also needs to verify that the documentation within the target repo meets a set of standards. `Doc-warden` is intended to ease the _implementation_ of these checks in CI builds.\n\nFeatures:\n\n* Enforces Readme Standards\n    - Readmes present\n    - Readmes have appropriate contents\n* Generates report for included observed packages\n\nThis package is tested on Python 2.7 -> 3.8.\n\n## Prerequisites\nThis package is intended to be run as part of a pipeline within Azure DevOps. As such, [Python](https://www.python.org/downloads/) must be installed prior to attempting to install or use `Doc-Warden.` While `pip` comes pre-installed on most modern Python installs, if `pip` is an unrecognized command when attempting to install `warden`, run the following command **after** your Python installation is complete.\n\nIn addition, `warden` is distributed using `setuptools` and `wheel`, so those packages should also be present prior to install. \n\n```\n/:> python -m ensurepip\n/:> pip install setuptools wheel\n```\n\n## Usage\n\nRight now, `warden` supports two main purposes. Readme enforcement (`scan`, `content`, `presence`) and package indexing (`index`).  \n\n### Example usage (for any of the above commands):\n\n```\n\n<pre-step, clone target repository>\n...\n/:> pip install setuptools wheel\n/:> pip install doc-warden\n...\n<next task, because PATH doesn't update without another one>\n/:> ward scan -d $(Build.SourcesDirectory)\n\n```\n**Notes for example above**\n\n* Assumption is that the `.docsettings` file is placed at the root of the repository.\n\nTo provide a different path (like `azure-sdk-for-java` does...), use: \n\n```\n\n/:> ward scan -d $(Build.SourcesDirectory) -c $(Build.SourcesDirectory)/eng/.docsettings.yml\n\n```\n\n##### Parameter Options\n\n`command` \nCurrently supports 3 commands. Values: `['scan', 'presence', 'content', `index`]` **Required.**\n\n* `scan`\n    * Run both `content` and `presence` enforcement on the targeted directory.\n* `content`\n    * Run only `content` readme enforcement on the target directory. Ensures content in each matches the regex patterns defined in the .docsettings file.\n* `presence` \n    * Run only `presence` readme enforcement on the target directory. Ensures readmes exist where they should.\n* `index`\n    * Take inventory of the target folder. Attempts to leverage selected docsettings to discover all packages within the directory, and generate a `packages.md` index file.\n\n`--scan-directory`\nThe target directory `warden` should be scanning. **Required.**\n\n`--scan-language`\n`warden` checks for packages by _convention_, so it needs to understand what language it is looking at. This must be populated either in `.docsettings file` or by parameter. **Required.**\n\n`--config-location`\nBy default, `warden` looks for the `.docsettings` file in the root of the repository. However, populating this location will override this behavior and instead pull the file from the location in this parameter. **Optional.**\n\n`--package-output`\nOverride the default location that the generated `packages.md` file is dropped to during execution of the `index` command.\n\n`--verbose-output`\nEnable or disable output of an html report. Defaults to false. **Optional.**\n\n##### Notes for Devops Usage\n\nThe `-d` argument should be `$(Build.SourcesDirectory)`. This will point `warden` at the repo that has been associated with CI.\n\n## Methodology\n\n### Enforcing Readme Presence \n\nWhen should we expect a readme to be present?\n\n**Always:**\n\n* At the root of the repo\n* Associated with a `package` directory\n\n#### .Net\n\nA package directory is indicated by:\n\n* a `*,csproj` file under the `sdk` directory\n    * Note that this is just a proxy. `warden` attempts to omit test projects by convention.\n\n\n#### Python\n\nA package directory is indicated by: \n\n* the presence of a `setup.py` file\n\n#### Java\n\nA package directory is indicated by:\n\n* the presence of a `pom.xml` file\n    * The POM `<packaging>` value within is set to `JAR`\n\n#### Node & JS\n\nA package directory is indicated by: \n\n* The presence of a `package.json` file\n\n### Enforcing Readme Content\n\n`doc-warden` has the ability to check discovered readme files to ensure that a set of configured sections is present. How does it work? `doc-warden` will ensure that each regex defined in `required_readme_sections` matches against at least one section header in the readme. If all the patterns match at least one header, the readme will pass content verification.\n\nOther Notes:\n\n* A `section` header is any markdown or RST that will result in a `<h1>` to `<h2>` html tag.\n* `warden` will content verify any `readme.rst` or `readme.md` file found outside the `omitted_paths` in the targeted repo. \n\n#### Control, the `.docsettings.yml` File, and You\n\nSpecial cases often need to be configured. It seems logical that there needs be a central location (per repo) to override conventional settings. To that end, a new `.docsettings.yml` file will be added to each repo. \n\n```\n<repo-root>\n\u2502   README.md\n\u2502   .docsettings.yml\n\u2502\n\u2514\u2500\u2500\u2500.azure-pipelines\n\u2502   \u2502   <build def>\n\u2502   \n\u2514\u2500\u2500\u2500<other files and folders>\n```\n\nThe presence of this file allows each repository to customize how enforcement takes place within their repo.\n\n**Example DocSettings File for Java Repo**\n\n```\nomitted_paths:\n  - archive/*\nlanguage: java\nroot_check_enabled: True\nrequired_readme_sections:\n  - \"(Client Library for Azure .*|Microsoft Azure SDK for .*)\"\n  - Getting Started\nknown_presence_issues:\n  - ['cognitiveservices/data-plane/language/bingspellcheck', '#2847']\nknown_content_issues:\n  - ['sdk/template/azure-sdk-template/README.md','#1368']\n```\n\nThe above configuration tells `warden`...\n\n- The language within the repo is `java`\n- To ensure that a `README.md` is present at the root of the repository.\n- To omit any paths under `archive/` from the readme checks.\n\nPossible values for `language` right now are `['net', 'java', 'js', 'python']`. Greater than one target language is not currently supported.\n\n##### `required_readme_sections` Configuration\nThis section instructs `warden` to verify that there is at least one matching section title for each provided `section` pattern in any discovered readme. Regex is fully supported.\n\nThe two items listed from the example `.docsettings` file will:\n- Match a header matched by a simple regex expression\n- Match a header exactly titled \"Getting Started\"\n\nNote that the regex is surrounded by quotation marks where the regex will break `yml` parsing of the configuration file.\n\n##### `known_presence_issues` and `known_content_issues` Configuration\n`doc-warden` is designed to crash builds if it detects failures. However, the vast majority of the time, these issues cannot be fixed immediately. In the above configuration, there are two paths highlighted as known issues. \n\nThe first, `known_presence_issues`, tells warden that a presence failure detected at the specified paths _should be ignored_ and should not result in a crashed build. A `tuple` describing each known issue specifies both what the known issue is, as well as some sort of justification. Having an exception with an issueId attached is a good justification for not failing the build.\n\n> We're aware of this issue, and it is tracked in the following github issue.\n\nThe `known_content_issues` parameter functions _identically_ to the `known_presence_issues` check. If a readme is listed as \"already known\" to have failures, the entire CI build will not be crashed by Warden.\n\n##### `package_indexing_exclusion_list` and `package_indexing_traversal_stops` Configuration\nIndexing packages is often done as part of nightly (or triggered) automation. With this being the case, sometimes `warden` may detect a PackageId that users wish to omit from the generated `packages.md` file. The Azure SDK team leverages \nthe `package_indexing_exclusion_list` array members to enable just this sort of scenario.\n\n`package_indexing_traversal_stops` is used during parse of .NET language repos _only_. This is due to how the discovery logic for readme and changelog is implemented for .NET projects. Specifically, readmes for a .csproj are often a couple directories up from their parent .csproj location!\n\nFor .net, `warden` will traverse **up** one directory at a time, looking for the readme and changelog files in each traversed directory. `warden` will continue to traverse until...\n\n1. It discovers a folder with a `.sln` within it\n2. It encounters a folder that exactly matches one present in `package_indexing_traversal_stops`\n\nNote that `warden` will not even execute an index against a .NET repo _unless the traversal stops are set_. \n\n[SDK for net .docsettings](https://github.com/Azure/azure-sdk-for-net/blob/master/eng/.docsettings.yml) is a great example for both the exclusion list as well as the traversal stops.\n\n## Provide Feedback\n\nIf you encounter any bugs or have suggestions, please file an issue [here](https://github.com/Azure/azure-sdk-tools/issues) and assign to `scbedd`.\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/Azure/azure-sdk-tools/",
        "keywords": "",
        "license": "MIT License",
        "maintainer": "",
        "maintainer_email": "",
        "name": "doc-warden",
        "package_url": "https://pypi.org/project/doc-warden/",
        "platform": "",
        "project_url": "https://pypi.org/project/doc-warden/",
        "project_urls": {
            "Homepage": "https://github.com/Azure/azure-sdk-tools/"
        },
        "release_url": "https://pypi.org/project/doc-warden/0.3.0/",
        "requires_dist": [
            "pyyaml",
            "markdown2",
            "docutils",
            "pygments",
            "beautifulsoup4",
            "jinja2",
            "requests",
            "pathlib"
        ],
        "requires_python": "",
        "summary": "Doc-Warden is an internal project created by the Azure SDK Team. It is intended to be used by CI Builds to ensure that documentation standards are met. See readme for more details.",
        "version": "0.3.0"
    },
    "last_serial": 5214498,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "77f49cbd7274bc334f99505fb1786037",
                    "sha256": "400a0badeb46a8cc8dbd7f0da3e96723e80d166046ab3cce155eeb47ad8f2e17"
                },
                "downloads": -1,
                "filename": "doc_warden-0.1.0-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "77f49cbd7274bc334f99505fb1786037",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 8364,
                "upload_time": "2019-02-15T18:42:24",
                "url": "https://files.pythonhosted.org/packages/95/aa/a0cdbd1d5444a88324cc9ccb9169a2ea5c766cd68847d81afc6c0bd4908a/doc_warden-0.1.0-py2.py3-none-any.whl"
            }
        ],
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "fde8d6d851ce463b9caab6b609917c20",
                    "sha256": "b8d8fc21d4997d76e1977f1d6d79f54a0c0e4baa2c4d691c7ae176a16cf9f927"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.0-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "fde8d6d851ce463b9caab6b609917c20",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12055,
                "upload_time": "2019-03-14T21:19:24",
                "url": "https://files.pythonhosted.org/packages/dd/67/a5090594e5a5a30deab9a8bb0ba32684e208551bf61629721035f58e7429/doc_warden-0.2.0-py2.py3-none-any.whl"
            }
        ],
        "0.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "042aaed9f7b2f46a0a00dea73c3593a1",
                    "sha256": "43700593706f43b0920f0528fae86dc4266ca272c16e0f299bb94f9828aad052"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.1-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "042aaed9f7b2f46a0a00dea73c3593a1",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12034,
                "upload_time": "2019-03-15T17:53:48",
                "url": "https://files.pythonhosted.org/packages/5e/8f/d02e056598b875fba8977107c21ebd9e10f3de04d9e163be827fff06555f/doc_warden-0.2.1-py2.py3-none-any.whl"
            }
        ],
        "0.2.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "144a578bd7c6933f18e9d383755e8d48",
                    "sha256": "9ca8edcbb094128d30c9630f3365fb1dd39181d42001afc9c2d53333c0e25895"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.2-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "144a578bd7c6933f18e9d383755e8d48",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12468,
                "upload_time": "2019-03-28T22:02:47",
                "url": "https://files.pythonhosted.org/packages/d2/0d/d008af24b3b7da99de99fc60a86ae24ecd834045e91007a646abd5b29c16/doc_warden-0.2.2-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "4e1ba74acd02c89f326bcbe8fb3d840c",
                    "sha256": "6f7084f4aa68fe1b4df899970d76fe013042789eb75b0eeae453d3fdc89c184d"
                },
                "downloads": -1,
                "filename": "doc-warden-0.2.2.zip",
                "has_sig": false,
                "md5_digest": "4e1ba74acd02c89f326bcbe8fb3d840c",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20884,
                "upload_time": "2019-03-28T22:02:49",
                "url": "https://files.pythonhosted.org/packages/27/1e/bdf82f7624d113df6a5902368265b6c23f67b7cf24c30fefcfd9e74c42b9/doc-warden-0.2.2.zip"
            }
        ],
        "0.2.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "355e7ce1c2fd10d45cb3c8813045ffe6",
                    "sha256": "749af37d7f8f61e1ae8c1cf1be86343405ffb1028b1b9ede9c9452c38be6a455"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.3-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "355e7ce1c2fd10d45cb3c8813045ffe6",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12467,
                "upload_time": "2019-03-29T00:00:54",
                "url": "https://files.pythonhosted.org/packages/f0/1c/4744d1cc00ea642a04323274feff6727ba74e553f2a4799914d61b147965/doc_warden-0.2.3-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "3bc3699e74435f6f16e1ce0e7ffecafe",
                    "sha256": "a4c78c1dc3ff9ed5d9d47f0ccd946954a33bcf6beb02a06c14b0b327c067cf00"
                },
                "downloads": -1,
                "filename": "doc-warden-0.2.3.zip",
                "has_sig": false,
                "md5_digest": "3bc3699e74435f6f16e1ce0e7ffecafe",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20884,
                "upload_time": "2019-03-29T00:00:55",
                "url": "https://files.pythonhosted.org/packages/30/06/c00f3558583f9108e4db57ca9b1f086dbd844f45f4d132ab1af691a0ae33/doc-warden-0.2.3.zip"
            }
        ],
        "0.2.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "fd7fde18d56d8ac9afe9cfd6df9a5196",
                    "sha256": "e453fd397ad75e066cd47f5916219d6d455765d05318078a003a6745faecaa30"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.4-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "fd7fde18d56d8ac9afe9cfd6df9a5196",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12471,
                "upload_time": "2019-04-01T23:58:32",
                "url": "https://files.pythonhosted.org/packages/47/75/d70e3abb4b62f8a6419e94ebdcdce20db1c33417f9e0c25edcc9281abafe/doc_warden-0.2.4-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "6c597270a9bfd0f1694830dc35a6c833",
                    "sha256": "77624978f1abea3472d7aa8e1f40a23cff295884f4256f87c42adcb4e91780ba"
                },
                "downloads": -1,
                "filename": "doc-warden-0.2.4.zip",
                "has_sig": false,
                "md5_digest": "6c597270a9bfd0f1694830dc35a6c833",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20927,
                "upload_time": "2019-04-01T23:58:34",
                "url": "https://files.pythonhosted.org/packages/b4/cc/4118eaea5e6a83e5c36b783cd0a654e4344195b1a2e0ce4c4d83dcd8850e/doc-warden-0.2.4.zip"
            }
        ],
        "0.2.5": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4014df70bc95b55b8b4b3ece4e6df98c",
                    "sha256": "4e9204cc0c26ac5b764ca6837cf00a912c746beb270662f6d11bea60fc14f171"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.5-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "4014df70bc95b55b8b4b3ece4e6df98c",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12471,
                "upload_time": "2019-04-03T01:04:58",
                "url": "https://files.pythonhosted.org/packages/ee/be/07ba42d1101acc9b69160766d896421132bb545118fc01879cf7d0b22be9/doc_warden-0.2.5-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "eaf1a00fc66e32ffd58004244016bae3",
                    "sha256": "c85635f991b710f73d751702ffbf0f445b5f764456923bbdea9c7737535083ed"
                },
                "downloads": -1,
                "filename": "doc-warden-0.2.5.zip",
                "has_sig": false,
                "md5_digest": "eaf1a00fc66e32ffd58004244016bae3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 20925,
                "upload_time": "2019-04-03T01:04:59",
                "url": "https://files.pythonhosted.org/packages/4f/6a/5fee61aa39c18839fd01d376896ae2fcf6345350e7da14940f0b730806e5/doc-warden-0.2.5.zip"
            }
        ],
        "0.2.6": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "61f6a173e583009dd85b7c906d4e3aaa",
                    "sha256": "68c9365587437dd77202ccf6a68ac48f9db88f4697eaa3816ed8f4e3367f5560"
                },
                "downloads": -1,
                "filename": "doc_warden-0.2.6-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "61f6a173e583009dd85b7c906d4e3aaa",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 12474,
                "upload_time": "2019-04-16T01:30:37",
                "url": "https://files.pythonhosted.org/packages/ac/95/a0f998c549763841f3e4b084512417966e4c85e47f766089c355b81f0384/doc_warden-0.2.6-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "6104e04618ca4e89b0936fc9f8a4cd67",
                    "sha256": "404a93452929adc4d7942a0556d6c84db7937a43093b0b7032b4c378f81459a2"
                },
                "downloads": -1,
                "filename": "doc-warden-0.2.6.zip",
                "has_sig": false,
                "md5_digest": "6104e04618ca4e89b0936fc9f8a4cd67",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 21733,
                "upload_time": "2019-04-16T01:30:39",
                "url": "https://files.pythonhosted.org/packages/4e/1b/8e4c971ade27195deb77647c30e910c063251b00ed63bd72983acd914007/doc-warden-0.2.6.zip"
            }
        ],
        "0.3.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "fcff29829f7eb5b19c528d626222ff14",
                    "sha256": "8e4e00ad817213766f705382e70ea3ce0c218d2e99b0bc7dc03379a1e243a00e"
                },
                "downloads": -1,
                "filename": "doc_warden-0.3.0-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "fcff29829f7eb5b19c528d626222ff14",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 19589,
                "upload_time": "2019-05-01T22:04:14",
                "url": "https://files.pythonhosted.org/packages/34/92/344490a76cb13d1b7fc4b4aa964f11e4867501ac013b226e2756cc9a897f/doc_warden-0.3.0-py2.py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "1014f27c4eb8bfd9ad42cbc38b4bcf66",
                    "sha256": "8310de6339ac6c68b03fe6e7b16562596749237875327febefe74392f6bd06ef"
                },
                "downloads": -1,
                "filename": "doc-warden-0.3.0.zip",
                "has_sig": false,
                "md5_digest": "1014f27c4eb8bfd9ad42cbc38b4bcf66",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 30487,
                "upload_time": "2019-05-01T22:04:16",
                "url": "https://files.pythonhosted.org/packages/5f/28/758a283eefc2ee0078100f80fb368b2e6da395d959debad0566a3a7ff1e0/doc-warden-0.3.0.zip"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "fcff29829f7eb5b19c528d626222ff14",
                "sha256": "8e4e00ad817213766f705382e70ea3ce0c218d2e99b0bc7dc03379a1e243a00e"
            },
            "downloads": -1,
            "filename": "doc_warden-0.3.0-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fcff29829f7eb5b19c528d626222ff14",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 19589,
            "upload_time": "2019-05-01T22:04:14",
            "url": "https://files.pythonhosted.org/packages/34/92/344490a76cb13d1b7fc4b4aa964f11e4867501ac013b226e2756cc9a897f/doc_warden-0.3.0-py2.py3-none-any.whl"
        },
        {
            "comment_text": "",
            "digests": {
                "md5": "1014f27c4eb8bfd9ad42cbc38b4bcf66",
                "sha256": "8310de6339ac6c68b03fe6e7b16562596749237875327febefe74392f6bd06ef"
            },
            "downloads": -1,
            "filename": "doc-warden-0.3.0.zip",
            "has_sig": false,
            "md5_digest": "1014f27c4eb8bfd9ad42cbc38b4bcf66",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 30487,
            "upload_time": "2019-05-01T22:04:16",
            "url": "https://files.pythonhosted.org/packages/5f/28/758a283eefc2ee0078100f80fb368b2e6da395d959debad0566a3a7ff1e0/doc-warden-0.3.0.zip"
        }
    ]
}