{
"info": {
"author": "Jason Antman",
"author_email": "jason@jasonantman.com",
"bugtrack_url": null,
"classifiers": [
"Development Status :: 1 - Planning",
"Environment :: Console",
"Intended Audience :: Developers",
"Intended Audience :: Information Technology",
"Intended Audience :: System Administrators",
"License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)",
"Natural Language :: English",
"Operating System :: OS Independent",
"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",
"Topic :: Documentation"
],
"description": "github-docs-index\n=================\n\n.. image:: https://img.shields.io/pypi/v/github-docs-index.svg?maxAge=2592000\n :target: https://pypi.org/project/github-docs-index\n :alt: pypi version\n\n.. image:: https://img.shields.io/github/forks/jantman/github-docs-index.svg\n :alt: GitHub Forks\n :target: https://github.com/jantman/github-docs-index/network\n\n.. image:: https://img.shields.io/github/issues/jantman/github-docs-index.svg\n :alt: GitHub Open Issues\n :target: https://github.com/jantman/github-docs-index/issues\n\n.. image:: https://secure.travis-ci.org/jantman/github-docs-index.png?branch=master\n :target: http://travis-ci.org/jantman/github-docs-index\n :alt: travis-ci for master branch\n\n.. image:: https://codecov.io/github/jantman/github-docs-index/coverage.svg?branch=master\n :target: https://codecov.io/github/jantman/github-docs-index?branch=master\n :alt: coverage report for master branch\n\n.. image:: https://readthedocs.org/projects/github-docs-index/badge/?version=latest\n :target: https://readthedocs.org/projects/github-docs-index/?badge=latest\n :alt: sphinx documentation for latest release\n\n.. image:: http://www.repostatus.org/badges/latest/wip.svg\n :alt: Project Status: WIP \u2013 Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.\n :target: http://www.repostatus.org/#wip\n\nGenerate a single-page index of documentation hosted in one or more GitHub organizations on github.com and/or one or more GitHub Enterprise instances.\n\nThis package is intended for organizations that host their documentation alongside code on GitHub (including GitHub Enterprise) and need a convenient single-page index to help people find things. It's a small, opinionated, and purpose-specific tool, originally written so that my team could have a master index of our documentation (spread across github.com, two GitHub Enterprises, Confluence, and another intranet solution) without having to remember to add every new repository.\n\n**Full documentation is available on ReadTheDocs:** http://github-docs-index.readthedocs.io/en/latest/\n\nFeatures\n--------\n\n* Outputs docutils-ready reStructuredText for processing or conversion to a variety of formats.\n* Supports a manually-curated \"quick links\" section at the top of the page, which can include arbitrary non-GitHub URLs\n* Iterates repositories in any number of Organizations (or Users) on github.com and/or any number of GitHub Enterprise instances. Allows blacklisting or whitelisting repositories per-org/user and blacklisting organizations.\n* Output sorted alphabetically and by last commit/update date.\n* Configurable to show only repositories with GitHub Pages, a Repository URL, repositories with a README file longer than a specified length, repositories with a description, or all repositories.\n* Option to ignore forks.\n* Python API which allows injecting additional links to the chronological and alphabetical lists.\n* GitHub tokens taken from environment variables.\n* Configurable title, subtitle/header and footer; subtitle and footer can be overridden by environment variables.\n\nRequirements\n------------\n\n* Python 2.7 or 3.4+ (currently tested with 2.7, 3.4, 3.5, 3.6)\n* `VirtualEnv `_ and ``pip`` (recommended installation method; your OS/distribution should have packages for these)\n\nInstallation\n------------\n\nIt's recommended that you install into a virtual environment (virtualenv /\nvenv). See the `virtualenv usage documentation `_\nfor information on how to create a venv.\n\n.. code-block:: bash\n\n pip install github-docs-index\n\nConfiguration\n-------------\n\nConfiguration is provided by a YAML file; see `example_config.yaml `_ for a detailed example. The YAML file must have a mapping/hash/dict at the top level. Keys are as follows:\n\n* **title**, string, the title of the index rst document\n* **footer**, *optional*, string, a footer line to include at the end of the index rst document. This configuration option is overridden by the ``GITHUB_DOCS_FOOTER`` environment variable if set.\n* **subtitle**, *optional*, string, a subtitle/header line to include below the title of the index rst document. This configuration option is overridden by the ``GITHUB_DOCS_SUBTITLE`` environment variable if set.\n* **githubs**, array/list of mappings/dicts specifying the github instances to query. Each item in the array has the following structure:\n\n * **token_env_var**, string, name of the environment variable that contains the Personal Access Token for this github instance\n * **url**, *optional*, string, URL to this GitHub instance for GitHub Enterprise instances. If not specified, defaults to ``https://api.github.com``\n * **orgs**, *optional*, array of string organization names to scan repositories in. If neither this option nor \"orgs\" is specified, default to scanning all repos of orgs that the authenticated user belongs to.\n * **users**, *optional*, array of string user names to scan repositories in. If neither this option nor \"orgs\" is specified, default to scanning all repos of orgs that the authenticated user belongs to.\n * **whitelist_repos**, *optional*, array of string repository slugs (full names) in \"owner_name/repo_name\" format. If specified, only these repos will be included regardless of other configuration for this GitHub instance.\n * **blacklist_repos**, *optional*, array of string repository slugs (full names) in \"owner_name/repo_name\" format to never include in the output documentation index.\n * **blacklist_orgs**, *optional*, array of string organization names to ignore when scanning repos.\n\n* **ignore_forks**, *optional*, boolean, default False. If True, do not include any repos that are forks in the listing.\n* **quick_links**, *optional*, array/list of mappings/dicts specifying manually-curated links to add to the \"Quick Links\" section at the top of the document. Each item in the array has the following structure:\n\n * **title** string, the title/text of the link\n * **url** string, the URL to link to\n * **description**, *optional*, string description to output after the link to the repo\n\n* **repo_criteria**, array/list of strings or mappings determining which repos to include in the listing and what URL to set for them. For each repo, these are evaluated in order and the first match wins; if none match, the repo is not added to the list. Possible options are:\n\n * ``homepage``, string: if present, use the Repository Homepage URL (at the top of the repo page, next to the description) as the link. Only matches repos with a Homepage set.\n * ``github_pages``, string: if present, use the repo's GitHub Pages URL as the link. Only matches repos with GitHub Pages enabled.\n * ``readme: N``, mapping/dict where \"readme\" is a string and N is an integer: match repos with a readme file of size N or greater, and link to the repo's main HTML URL (github web UI URL)\n * ``description``, string: match any repo with a description set, and link to the repo's main HTML URL (github web UI URL)\n * ``all`` match any/all repos, and link to the repo's main HTML URL (github web UI URL)\n\nCLI Usage\n---------\n\nUsage via the command line is straightforward for common use cases. The reStructuredText output is printed to STDOUT, and can be redirected to a file. For example, assuming you've already installed the package as shown above, and using ``example_config.yaml`` as an example:\n\n.. code-block:: bash\n\n # these next three environment variable names are specified in example_config.yaml\n export GITHUB_TOKEN=yourToken\n export GHE_TOKEN=anotherToken\n export OTHER_GHE_TOKEN=yetAnotherToken\n github-docs-index config.yaml > index.rst\n\nThis rst file can be converted to the format of your choice with any tool that understands reStructuredText input. For example, it can be converted to HTML using ``rst2html.py`` from the `docutils `_ package (``pip install docutils``):\n\n.. code-block:: bash\n\n rst2html.py --report=4 index.rst > index.html\n\nSetting Subtitle and Footer\n---------------------------\n\nThe optional subtitle (line below the title) and footer (line at the bottom of the document) can also be specified as environment variables. For example:\n\n.. code-block:: bash\n\n export GITHUB_DOCS_SUBTITLE=\"This document was automatically generated at $(date)\"\n export GITHUB_DOCS_FOOTER=\"This document was generated by Jenkins: ${BUILD_URL}\"\n github-docs-index config.yaml > index.rst\n\nExample Output\n--------------\n\nYou can see an example of the actual HTML output for my own github user in the source tree at `example_output.rst `_.\n\nPython Usage\n------------\n\ngithub-docs-index can also be imported and used in other Python code. This can be especially useful for doing something with the raw rst output; here is an example that replicates the functionality of the above CLI examples in a single Python script:\n\n.. code-block:: python\n\n #!/usr/bin/env python\n\n # for generating the rst\n from github_docs_index.config import Config\n from github_docs_index.index_generator import GithubDocsIndexGenerator\n\n # for docutils rst -> HTML\n from docutils import core\n from docutils.writers.html4css1 import Writer, HTMLTranslator\n\n\n # this replicates \"github-docs-index config.yaml\" at the command line\n g = GithubDocsIndexGenerator(Config('config.yaml'))\n rst_string = g.generate_index()\n\n # the code below here replicates \"rst2html.py --report=4 index.rst > index.html\"\n\n\n class HTMLFragmentTranslator(HTMLTranslator):\n\n def __init__(self, document):\n HTMLTranslator.__init__(self, document)\n self.head_prefix = ['', '', '', '', '']\n self.body_prefix = []\n self.body_suffix = []\n self.stylesheet = []\n\n def astext(self):\n return ''.join(self.body)\n\n\n html_fragment_writer = Writer()\n html_fragment_writer.translator_class = HTMLFragmentTranslator\n\n with open('index.html', 'wb') as fh:\n fh.write(core.publish_string(rst_string, writer=html_fragment_writer))\n print('Output written to: index.html')\n\nAdding Documentation From Other Sources\n+++++++++++++++++++++++++++++++++++++++\n\nIt's also possible via the Python API to include aribtrary documents from sources other than GitHub in the index; they will be sorted into the chronological and alphabetical lists along with the GitHub repositories. This can be helpful if you have other sources of documentation such as an Intranet or Wiki that you can programmatically query. The only requirement is that each document has a URL, title, date (generally a created/modified/updated date) and optional short description. The `GithubDocsIndexGenerator.generate_index `_ method takes an optional ``additional_links`` argument which is a list of instances of a subclass of `github_docs_index.index_link.IndexLink `_. So long as the instances implement the three properties of ``IndexLink``, they will be included in the documentation index. Here is a short, contrived example based on the code above which includes two other documents with hard-coded dates, titles and URLs; the ``generate_additional_links()`` function could be switched out for one which queries your alternate documentation stores and returns similar output.\n\n.. code-block:: python\n\n #!/usr/bin/env python3\n\n from datetime import datetime, timezone\n from github_docs_index.config import Config\n from github_docs_index.index_generator import GithubDocsIndexGenerator\n from github_docs_index.index_link import IndexLink\n\n\n class StaticLink(IndexLink):\n \"\"\"This class implements the three property methods in IndexLink\"\"\"\n\n def __init__(self, title, url, sort_datetime, description=''):\n self._title = title\n self._url = url\n self._sort_datetime = sort_datetime\n self._description = description\n\n @property\n def sort_datetime(self):\n return self._sort_datetime\n\n @property\n def sort_name(self):\n return self._title.lower()\n\n @property\n def rst_line(self):\n r = '`%s <%s>`_' % (self._title, self._url)\n if self._description is not None and self._description.strip() != '':\n r += ' - ' + self._description\n return r\n\n\n def generate_additional_links():\n return [\n StaticLink(\n 'Some Document', 'http://example.com/someDocument',\n datetime(2017, 6, 3, 12, 34, 41, tzinfo=timezone.utc),\n description='this is a document'\n ),\n StaticLink(\n 'Other Document', 'http://example.com/otherDocument',\n datetime(2018, 8, 12, 19, 24, 53, tzinfo=timezone.utc),\n description='this is another document'\n )\n ]\n\n\n # this replicates \"github-docs-index config.yaml\" at the command line\n g = GithubDocsIndexGenerator(Config('config.yaml'))\n rst_string = g.generate_index(additional_links=generate_additional_links())\n\n with open('index.rst', 'w') as fh:\n fh.write(rst_string)\n\nBugs and Feature Requests\n-------------------------\n\nBug reports and feature requests are happily accepted via the `GitHub Issue Tracker `_. Pull requests are\nwelcome. Issues that don't have an accompanying pull request will be worked on\nas my time and priority allows.\n\nDevelopment\n===========\n\nTo install for development:\n\n1. Fork the `github-docs-index `_ repository on GitHub\n2. Create a new branch off of master in your fork.\n\n.. code-block:: bash\n\n $ virtualenv github-docs-index\n $ cd github-docs-index && source bin/activate\n $ pip install -e git+git@github.com:YOURNAME/github-docs-index.git@BRANCHNAME#egg=github-docs-index\n $ cd src/github-docs-index\n\nThe git clone you're now in will probably be checked out to a specific commit,\nso you may want to ``git checkout BRANCHNAME``.\n\nGuidelines\n----------\n\n* pep8 compliant with some exceptions (see pytest.ini)\n* 100% test coverage with pytest (with valid tests)\n\nTesting\n-------\n\nTesting is done via `pytest `_, driven by `tox `_.\n\n* testing is as simple as:\n\n * ``pip install tox``\n * ``tox``\n\n* If you want to pass additional arguments to pytest, add them to the tox command line after \"--\". i.e., for verbose pytext output on py27 tests: ``tox -e py27 -- -v``\n\nRelease Checklist\n-----------------\n\n1. Open an issue for the release; cut a branch off master for that issue.\n2. Confirm that there are CHANGES.rst entries for all major changes.\n3. Ensure that Travis tests passing in all environments.\n4. Ensure that test coverage is no less than the last release (ideally, 100%).\n5. Increment the version number in github-docs-index/version.py and add version and release date to CHANGES.rst, then push to GitHub.\n6. Confirm that README.rst renders correctly on GitHub.\n7. Upload package to testpypi:\n\n * Make sure your ~/.pypirc file is correct (a repo called ``test`` for https://test.pypi.org/)\n * ``rm -Rf dist``\n * ``python setup.py sdist bdist_wheel``\n * ``twine upload -r test dist/*``\n * Check that the README renders at https://test.pypi.org/project/github-docs-index\n\n8. Create a pull request for the release to be merged into master. Upon successful Travis build, merge it.\n9. Tag the release in Git, push tag to GitHub:\n\n * tag the release. for now the message is quite simple: ``git tag -s -a X.Y.Z -m 'X.Y.Z released YYYY-MM-DD'``\n * push the tag to GitHub: ``git push origin X.Y.Z``\n\n11. TravisCI will cut the release and upload to PyPI.\n\n\n",
"description_content_type": "",
"docs_url": null,
"download_url": "",
"downloads": {
"last_day": -1,
"last_month": -1,
"last_week": -1
},
"home_page": "https://github.com/jantman/github-docs-index",
"keywords": "github documentation index html docutils",
"license": "",
"maintainer": "",
"maintainer_email": "",
"name": "github-docs-index",
"package_url": "https://pypi.org/project/github-docs-index/",
"platform": "",
"project_url": "https://pypi.org/project/github-docs-index/",
"project_urls": {
"Homepage": "https://github.com/jantman/github-docs-index"
},
"release_url": "https://pypi.org/project/github-docs-index/0.1.2/",
"requires_dist": [
"PyYAML (<4.0,>=3.0)",
"github3.py (<2.0.0,>=1.1.0)"
],
"requires_python": "",
"summary": "Generate a single-page index of documentation hosted in one or more GitHub organizations on github.com and/or one or more GitHub Enterprise instances.",
"version": "0.1.2"
},
"last_serial": 3789124,
"releases": {
"0.1.0": [
{
"comment_text": "",
"digests": {
"md5": "422264466aa33234254963d48eaaf517",
"sha256": "31c574d4bb81f1c15ca326c6f6f5317925b01e94f1d1049a12a41561b33efc7c"
},
"downloads": -1,
"filename": "github_docs_index-0.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "422264466aa33234254963d48eaaf517",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 34276,
"upload_time": "2018-04-22T00:30:48",
"url": "https://files.pythonhosted.org/packages/3b/c6/f4fd9c500edf5b124a058e8d6f812913a24456328362fedf4e07f3558cb2/github_docs_index-0.1.0-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "5e17b10e4ba4d4f3c2e4616b01b55f5e",
"sha256": "79936f89d21006f69ee2869a759ce3965c5e9e8d3b10f85584f3eb95e7f4c6bf"
},
"downloads": -1,
"filename": "github-docs-index-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "5e17b10e4ba4d4f3c2e4616b01b55f5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33368,
"upload_time": "2018-04-22T00:30:49",
"url": "https://files.pythonhosted.org/packages/49/b4/8b5cbefe50353bf330e6dbe2b49aa2fc7b1b27f04f5c782fec493b761522/github-docs-index-0.1.0.tar.gz"
}
],
"0.1.1": [
{
"comment_text": "",
"digests": {
"md5": "f2f328fe2322b8015f4e88fa69e27708",
"sha256": "cf56fff6d8178d07c32a48670fc811e9f0af5fd83c89bb8f62c327e31ce37b21"
},
"downloads": -1,
"filename": "github_docs_index-0.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2f328fe2322b8015f4e88fa69e27708",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 34334,
"upload_time": "2018-04-22T00:39:45",
"url": "https://files.pythonhosted.org/packages/2c/c7/a4858fc69ed1fea2d611c4a5fe7ddf2845035daaabc1a7b03d91998f0f93/github_docs_index-0.1.1-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "6b4af257e244ea6ed761d6704472589d",
"sha256": "42050ad4603d106e87d1202a7979b8446f726706df27227663f2970d754bec75"
},
"downloads": -1,
"filename": "github-docs-index-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "6b4af257e244ea6ed761d6704472589d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33398,
"upload_time": "2018-04-22T00:39:46",
"url": "https://files.pythonhosted.org/packages/0f/d9/17828fa16d2d78601f530b0648ace9ab1bccb76fdc72af289ab434eec4dd/github-docs-index-0.1.1.tar.gz"
}
],
"0.1.2": [
{
"comment_text": "",
"digests": {
"md5": "bebc9c406c68509ec74a189fc58bfa9a",
"sha256": "3a6bdff28d2d2b8ce0eacf1aa6a0e556608ddcf87c3b71b725a11a311c7d69db"
},
"downloads": -1,
"filename": "github_docs_index-0.1.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "bebc9c406c68509ec74a189fc58bfa9a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 34329,
"upload_time": "2018-04-22T15:22:13",
"url": "https://files.pythonhosted.org/packages/88/e5/6ebaac17b8bc1c67fdac11621fe6aade05d82009f54147c2c866443de0f5/github_docs_index-0.1.2-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "14895d836deaaef2dd09f5492f8e5c9b",
"sha256": "ee430ee6ba087e80537e47d3f8b73ccd016395901a654d6de534ebf675d9b94b"
},
"downloads": -1,
"filename": "github-docs-index-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "14895d836deaaef2dd09f5492f8e5c9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33422,
"upload_time": "2018-04-22T15:22:14",
"url": "https://files.pythonhosted.org/packages/05/9d/6d0a82f5f35413fd161705353a5874aefda7faf38c9d2627f8c32a0be38e/github-docs-index-0.1.2.tar.gz"
}
]
},
"urls": [
{
"comment_text": "",
"digests": {
"md5": "bebc9c406c68509ec74a189fc58bfa9a",
"sha256": "3a6bdff28d2d2b8ce0eacf1aa6a0e556608ddcf87c3b71b725a11a311c7d69db"
},
"downloads": -1,
"filename": "github_docs_index-0.1.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "bebc9c406c68509ec74a189fc58bfa9a",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 34329,
"upload_time": "2018-04-22T15:22:13",
"url": "https://files.pythonhosted.org/packages/88/e5/6ebaac17b8bc1c67fdac11621fe6aade05d82009f54147c2c866443de0f5/github_docs_index-0.1.2-py2.py3-none-any.whl"
},
{
"comment_text": "",
"digests": {
"md5": "14895d836deaaef2dd09f5492f8e5c9b",
"sha256": "ee430ee6ba087e80537e47d3f8b73ccd016395901a654d6de534ebf675d9b94b"
},
"downloads": -1,
"filename": "github-docs-index-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "14895d836deaaef2dd09f5492f8e5c9b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 33422,
"upload_time": "2018-04-22T15:22:14",
"url": "https://files.pythonhosted.org/packages/05/9d/6d0a82f5f35413fd161705353a5874aefda7faf38c9d2627f8c32a0be38e/github-docs-index-0.1.2.tar.gz"
}
]
}