在github.com和/或一个或多个github企业实例上生成托管在一个或多个github组织中的文档的单页索引。
github-docs-index的Python项目详细描述
Github文档索引
在github.com和/或一个或多个github企业实例上生成托管在一个或多个github组织中的文档的单页索引。
这个包是为那些在github（包括github enterprise）上托管文档并需要一个方便的单页索引来帮助人们查找内容的组织设计的。这是一个小型的、固执己见的、针对特定目的的工具，最初是为了让我的团队能够拥有我们文档的主索引（分布在github.com、两家github企业、confluence和另一个intranet解决方案中），而无需记住添加每个新的存储库。
完整文档可在readthedocs上获得： http://github docs index.readthedocs.io/en/latest/
功能
- 输出docutils ready structuredtext，用于处理或转换为多种格式。
- 支持页面顶部手动管理的"快速链接"部分，其中可以包含任意非GitHub URL
- 迭代github.com上任意数量的组织（或用户）和/或任意数量的github企业实例中的存储库。允许每个组织/用户和黑名单组织将存储库列入黑名单或白名单。
- 按字母顺序和上次提交/更新日期排序的输出。
- 构造函数只能显示具有GitHub页面的存储库、存储库URL、具有超过指定长度的自述文件的存储库、具有说明的存储库或所有存储库。
- 忽略叉子的选项。
- python api，它允许向按时间顺序和字母顺序排列的列表插入其他链接。
- 从环境变量中获取的GitHub令牌。
- 可配置的标题、副标题/页眉和页脚；环境变量可以覆盖副标题和页脚。
要求
- python 2.7或3.4+（当前使用2.7、3.4、3.5、3.6进行测试）
- virtualenv 和 pip （建议的安装方法；您的操作系统/发行版应该有相应的软件包）
配置
配置由一个yaml文件提供；有关详细示例，请参见example-config.yaml。yaml文件的顶层必须有映射/hash/dict。按键如下：
- 标题 ，字符串，索引RST文档的标题
- 页脚 ， 可选 ，字符串，要包含在索引RST文档末尾的页脚行。如果已设置，此配置选项将被 github\u docs\u footer 环境变量覆盖。
- 副标题 ， 可选 ，字符串，要包含在索引rst文档标题下的副标题/标题行。如果已设置，此配置选项将被 github\u docs\u子标题 环境变量覆盖。
-
githubs
，指定要查询的github实例的映射/dict数组/列表。数组中的每个项都具有以下结构：
- token_env_var ，string，包含此github实例的个人访问令牌的环境变量的名称
- url ， 可选 ，字符串，github企业实例到此github实例的url。如果未指定，则默认为https://api.github.com
- 组织 ， 可选 ，要扫描存储库的字符串组织名称数组。如果未指定此选项或"orgs"，则默认扫描经过身份验证的用户所属的orgs的所有repo。
- 用户 ， 可选 ，要扫描存储库的字符串用户名数组。如果未指定此选项或"orgs"，则默认扫描经过身份验证的用户所属的orgs的所有repo。
- 白名单回购 ， 可选 ，以"所有者名称/回购名称"格式的字符串存储库段塞（全名）数组。如果指定，则无论此GitHub实例的其他配置如何，都只包括这些回购。
- 黑名单回购 ， 可选 ，以"所有者名称/回购名称"格式排列的字符串存储库段塞（全名），不包含在输出文档索引中。
- 黑名单组织 ， 可选 ，扫描回购时要忽略的字符串组织名称数组。
- 忽略叉子 ， 可选 ，布尔值，默认为false。如果为true，则不要在列表中包含任何分叉回购。
-
快速链接
，
可选
，指定要添加到文档顶部"快速链接"部分的手动管理链接的映射/dict数组/列表。数组中的每个项都具有以下结构：
- 标题 字符串，链接的标题/文本
- 网址 s字符串，链接到的URL
- 说明 ， 可选 ，链接到回购后要输出的字符串说明
-
回购条件，字符串或映射的数组/列表，确定要在列表中包含哪些回购以及要为它们设置的URL。对于每个repo，都是按顺序计算的，第一个匹配项获胜；如果没有匹配项，则不会将repo添加到列表中。可能的选项有：
- 主页 ，字符串：如果存在，请使用存储库主页url（位于repo页面顶部，描述旁边）作为链接。仅将回购与主页集匹配。
- github_pages ，字符串：如果存在，请使用repo的github pages url作为链接。仅匹配启用了Github页面的回购。
- readme:n ，mapping/dict，其中"readme"是一个字符串，n是一个整数：将repo s与大小为n或更大的readme文件匹配，并链接到repo的主html url（github web ui url）
- 说明 ，字符串：将任何repo与说明集匹配，并链接到repo的主html url（github web ui url）
- 全部 匹配任何/所有repo，并链接到repo的主html url（github web ui url）
cli用法
对于常见的用例，通过命令行使用非常简单。structuredText输出被打印到stdout，并可以重定向到文件。例如，假设您已经安装了如上所示的包，并使用 example\u config.yaml 作为示例：
# these next three environment variable names are specified in example_config.yaml exportGITHUB_TOKEN=yourToken exportGHE_TOKEN=anotherToken exportOTHER_GHE_TOKEN=yetAnotherToken github-docs-index config.yaml > index.rst
这个rst文件可以用任何理解structuredtext输入的工具转换为您选择的格式。例如，可以使用 docutils 包（ pip install docutils ）中的 rst2html.py 将其转换为html
rst2html.py --report=4 index.rst > index.html
设置字幕和页脚
可选的副标题（标题下面的一行）和页脚（文档底部的一行）也可以指定为环境变量。例如：
exportGITHUB_DOCS_SUBTITLE="This document was automatically generated at $(date)"exportGITHUB_DOCS_FOOTER="This document was generated by Jenkins: ${BUILD_URL}" github-docs-index config.yaml > index.rst
示例输出
在源代码树中，您可以看到我自己的github用户的实际html输出示例，网址是：example-output.rst
python用法
github文档索引也可以导入并在其他python代码中使用。这对于使用原始rst输出执行某些操作特别有用；下面是一个示例，它在单个python脚本中复制了上述cli示例的功能：
#!/usr/bin/env python# for generating the rstfromgithub_docs_index.configimportConfigfromgithub_docs_index.index_generatorimportGithubDocsIndexGenerator# for docutils rst -> HTMLfromdocutilsimportcorefromdocutils.writers.html4css1importWriter,HTMLTranslator# this replicates "github-docs-index config.yaml" at the command lineg=GithubDocsIndexGenerator(Config('config.yaml'))rst_string=g.generate_index()# the code below here replicates "rst2html.py --report=4 index.rst > index.html"classHTMLFragmentTranslator(HTMLTranslator):def__init__(self,document):HTMLTranslator.__init__(self,document)self.head_prefix=['','','','','']self.body_prefix=[]self.body_suffix=[]self.stylesheet=[]defastext(self):return''.join(self.body)html_fragment_writer=Writer()html_fragment_writer.translator_class=HTMLFragmentTranslatorwithopen('index.html','wb')asfh:fh.write(core.publish_string(rst_string,writer=html_fragment_writer))print('Output written to: index.html')
从其他来源添加文档
还可以通过python api在索引中包含来自github以外的源的aribtrary文档；它们将与github存储库一起被排序到按时间顺序和字母顺序排列的列表中。如果您有其他文档源（如可以编程查询的Intranet或Wiki），这将非常有用。唯一的要求是每个文档都有一个url、标题、日期（通常是创建/修改/更新日期）和可选的简短描述。方法采用可选的附加链接参数这是 github docs_index.index_link.indexlink 的子类的实例列表。只要这些实例实现了 indexlink 的三个属性，它们就会包含在文档索引中。下面是一个基于代码above包含另外两个带有硬编码日期、标题和url的文档；可以将 generate_additional_links（） 函数切换为查询备用文档存储并返回类似输出的函数。
#!/usr/bin/env python3fromdatetimeimportdatetime,timezonefromgithub_docs_index.configimportConfigfromgithub_docs_index.index_generatorimportGithubDocsIndexGeneratorfromgithub_docs_index.index_linkimportIndexLinkclassStaticLink(IndexLink):"""This class implements the three property methods in IndexLink"""def__init__(self,title,url,sort_datetime,description=''):self._title=titleself._url=urlself._sort_datetime=sort_datetimeself._description=description@propertydefsort_datetime(self):returnself._sort_datetime@propertydefsort_name(self):returnself._title.lower()@propertydefrst_line(self):r='`%s <%s>`_'%(self._title,self._url)ifself._descriptionisnotNoneandself._description.strip()!='':r+=' - '+self._descriptionreturnrdefgenerate_additional_links():return[StaticLink('Some Document','http://example.com/someDocument',datetime(2017,6,3,12,34,41,tzinfo=timezone.utc),description='this is a document'),StaticLink('Other Document','http://example.com/otherDocument',datetime(2018,8,12,19,24,53,tzinfo=timezone.utc),description='this is another document')]# this replicates "github-docs-index config.yaml" at the command lineg=GithubDocsIndexGenerator(Config('config.yaml'))rst_string=g.generate_index(additional_links=generate_additional_links())withopen('index.rst','w')asfh:fh.write(rst_string)
错误和功能请求
通过github问题跟踪程序，可以愉快地接受错误报告和功能请求。拉取请求是 欢迎。将处理没有附带拉取请求的问题 在我的时间和优先权允许的情况下。
欢迎加入QQ群-->： 979659372
