diff --git a/docs/index.md b/docs/index.md index 000ea34..6a7fb85 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,17 +1,15 @@ -# Welcome to MkDocs +# GitGuide -For full documentation visit [mkdocs.org](https://www.mkdocs.org). - -## Commands - -* `mkdocs new [dir-name]` - Create a new project. -* `mkdocs serve` - Start the live-reloading docs server. -* `mkdocs build` - Build the documentation site. -* `mkdocs -h` - Print help message and exit. - -## Project layout - - mkdocs.yml # The configuration file. - docs/ - index.md # The documentation homepage. - ... # Other markdown pages, images and other files. +* 规范 + * README编写 + * 消息提交 + * 版本提交 +* 工具 + * Git + * Commitizen + * conventioanl-changelog + * CommitLint+Husky + * generator-standard-readme +* 平台 + * GitLab + * GitHub \ No newline at end of file diff --git a/docs/readme/badge.md b/docs/readme/badge.md new file mode 100644 index 0000000..eda484c --- /dev/null +++ b/docs/readme/badge.md @@ -0,0 +1,28 @@ + +# 徽章 + +经常在`README`文件中发现许多徽章,很多都是使用[http://shields.io](http://shields.io/)或类似服务创建和托管的 + +## 自定义 + +进入`shields.io` + +![](./imgs/badge.png) + +输入标签名和徽章信息,选择颜色即可生成静态`SVG`图像 + +``` +https://img.shields.io/badge/ZHUJIAN-BADGE-brightgreen +``` + +![](https://img.shields.io/badge/ZHUJIAN-BADGE-brightgreen) + +## 添加链接 + +在徽章图像上添加链接,点击图像跳转到仓库 + +``` +[![](https://img.shields.io/badge/ZHUJIAN-BADGE-brightgreen)](https://shields.io) +``` + +[![](https://img.shields.io/badge/ZHUJIAN-BADGE-brightgreen)](https://shields.io) \ No newline at end of file diff --git a/docs/readme/imgs/badge.png b/docs/readme/imgs/badge.png new file mode 100644 index 0000000..037eab5 Binary files /dev/null and b/docs/readme/imgs/badge.png differ diff --git a/docs/readme/imgs/readme生成器.md b/docs/readme/imgs/readme生成器.md new file mode 100644 index 0000000..95672bc --- /dev/null +++ b/docs/readme/imgs/readme生成器.md @@ -0,0 +1,113 @@ + +# README生成器 + +[RichardLitt/generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme)提供了一个`npm`命令行工具,用于生成`README`文件 + +## 安装 + +``` +npm install --global yo generator-standard-readme +``` + +## 使用 + +命令行输入 + +``` +$ yo standard-readme +``` + +接下来会提出很多问题,然后生成一个README文件。所有问题如下: + +``` +What do you want to name your module? +What is the description of this module? +Do have a banner image? + Where is the banner image? Ex: 'img/banner.png' +Do you want a TODO dropped where your badges should be? +Do you want a TODO dropped where your long description should be? +Do you need a prioritized security section? +Do you need a background section? +Do you need an API section? +What is the GitHub handle of the main maintainer? +Do you have a CONTRIBUTING.md file? +Are PRs accepted? +Is an MIT license OK? + What is your license? +Who is the License holder (probably your name)? +Use the current year? + What years would you like to specify? +``` + +## 示例 + +``` +$ yo standard-readme +? ========================================================================== +We're constantly looking for ways to make yo better! +May we anonymously report usage statistics to improve the tool over time? +More info: https://github.com/yeoman/insight & http://yeoman.io +========================================================================== Yes +? What is the name of your module? zj +? What is the description of this module? yo使用示例 +? Do have a banner image? No +? Do you want a standard-readme compliant badge? Yes +? Do you want a TODO dropped where more badges should be? Yes +? Do you want a TODO dropped where your long description should be? Yes +? Do you need a prioritized security section? No +? Do you need a background section? Yes +? Do you need an API section? No +? What is the GitHub handle of the main maintainer? zjZSTU +? Do you have a CONTRIBUTING.md file? No +? Are PRs accepted? Yes +? Is an MIT license OK? Yes +? Who is the License holder (probably your name)? zjZSTU +? Use the current year? Yes + create README.md +``` + +生成文件如下: + + # zj // 标题 + + [![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) // 徽章 + TODO: Put more badges here. // 可以添加更多徽章 + + > yo使用示例 // 简短说明 + + TODO: Fill out this long description. // 详细说明 + + ## Table of Contents // 下面的章节列表,每个章节都可以点击跳转 + + - [Background](#background) + - [Install](#install) + - [Usage](#usage) + - [Maintainers](#maintainers) + - [Contributing](#contributing) + - [License](#license) + + ## Background // 背景 + + ## Install // 安装 + + ``` + ``` + + ## Usage // 用法 + + ``` + ``` + + ## Maintainers // 主要维护人员 + + [@zjZSTU](https://github.com/zjZSTU) + + ## Contributing // 参与贡献方式 + + PRs accepted. + + Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. + + ## License // 许可证 + + MIT © 2019 zjZSTU \ No newline at end of file diff --git a/docs/readme/index.md b/docs/readme/index.md new file mode 100644 index 0000000..bcb97a0 --- /dev/null +++ b/docs/readme/index.md @@ -0,0 +1,10 @@ + +# 如何写好README + +`README`常常是工程的第一个入口,经常不知道写些什么,如何介绍工程的内容。在网上找了资料,发现这是很多人遇到的问题,也有很多热心人士发表了自己的意见 + +主要参考[RichardLitt/standard-readme](https://github.com/RichardLitt/standard-readme),里面提出了一整套`REAMDE`规范,包括编写规范、`linter`、生成器、徽章以及示例 + +另外[kylelobo/The-Documentation-Compendium](https://github.com/kylelobo/The-Documentation-Compendium#templates)和[如何写好Github中的readme?](https://www.zhihu.com/question/29100816)也给出了很多建议 + +最终实现:[如何编写好的README](https://blog.zhujian.life/posts/79f69ebe.html) \ No newline at end of file diff --git a/docs/readme/postscript.md b/docs/readme/postscript.md new file mode 100644 index 0000000..df0c66b --- /dev/null +++ b/docs/readme/postscript.md @@ -0,0 +1,4 @@ + +# 后记 + +坚持README规范的编写对于仓库的维护确实很有用。在之后的学习过程中,我又发现了许多 \ No newline at end of file diff --git a/docs/readme/译-规范.md b/docs/readme/译-规范.md new file mode 100644 index 0000000..af14f5f --- /dev/null +++ b/docs/readme/译-规范.md @@ -0,0 +1,220 @@ + +# [译]规范 + +原文地址:[Specification](https://github.com/RichardLitt/standard-readme/blob/master/spec.md) + +## 引言 + +`README`必须满足下面列出的所有要求 + +>注意:标准自述文件是为开源库设计的。尽管它在历史上是为`node`和`npm`项目创建的,但它也适用于其他语言的库和包管理器 + +要求: + +* 称为`README.md`(大写) +* 如果项目支持[i18n](https://baike.baidu.com/item/I18N/6771940),则必须相应地命名该文件:`README.de.md`,其中`de`是[BCP 47](https://tools.ietf.org/html/bcp47)语言标记。对于命名,请优先考虑语言的非区域子标记。如果只有一个`README`且语言不是英语,则允许文本中使用不同的语言而无需指定`BCP`标记:例如README.md可以是德语。在包含多种语言版本的情况下,`README.md`固定为英语 +* 是一个有效的`Markdown`文件 +* 章节必须按下面给出的顺序出现。可省略可选部分 +* 除非另有说明,否则每个章节必须具有下面列出的标题。如果`README`是另一种语言,则必须将标题翻译成该语言 +* 不能包含无法访问链接 +* 如果有代码示例,则应该像在项目的其余部分中对代码进行`linted`一样对它们进行`linted` + +## 内容列表 + +>注意:这只是规范的导航指南,并不是任何符合规范的文档定义或强制使用术语 + +* 章节 + * 标题(`Title`) + * 横幅(`Banner`) + * 徽章(`Badges`) + * 简短说明(`Short Description`) + * 详细描述(`Long Description`) + * 内容列表(`Table of Contents`) + * 安全(`Security`) + * 背景(`Background`) + * 安装(`Install`) + * 用法(`Usage`) + * 附加内容(`Extra Sections`) + * 应用编程接口(`API`) + * 主要维护人员(`Maintainers`) + * 致谢(`Thanks`) + * 参与贡献方式(`Contributing`) + * 许可证(`License`) +* 定义 + +## 章节 + +### 标题 + +* 状态(`status`):必须 +* 必要条件(`requirements`): + * 标题必须与`repository、folder`和`package manager`名称匹配,或者它可以有另一个相关的标题,旁边的`repository、folder`和`package manager`标题用斜体字和括号括起来。例如: + + ``` + # Standard Readme Style _(standard-readme)_ + ``` + 如果任何文件夹、存储库或包管理器名称不匹配,则在详细描述中必须有一条说明原因 +* 建议(`suggestions`):符合内容要求,做到显而易见 + +### 横幅 + +* 状态:可选 +* 必要条件: + * 不能有自己的标题 + * 必须链接到当前存储库中的本地图像 + * 必须直接出现在标题后面 + +### 徽章 + +* 状态:可选 +* 必要条件: + * 不能有自己的标题 + * 必须用换行符分隔 +* 建议:使用[http://shields.io](http://shields.io/)或类似服务创建和托管图像 + +### 简短说明 + +* 状态:必须 +* 必要条件: + * 不能有自己的标题 + * 小于`120`个字符 + * 以`>`开始 + * 一定是单独一行 + * 必须与包装管理器`说明`字段中的描述匹配 + * 必须匹配`github`的描述(如果在`github`上) +* 建议(*`js`相关*): + * 使用`gh description`设置并获取`github`描述 + * 使用`npm show . description`显示本地`npm`包中的描述 + +### 详细描述 + +* 状态:可选 +* 必要条件: + * 不能有自己的标题 + * 如果任何文件夹、存储库或包管理器名称不匹配,必须在此处说明原因。参考[标题](https://github.com/RichardLitt/standard-readme/blob/master/spec.md#title) +* 建议: + * 如果太长,考虑移动到背景章节 + * 介绍构建存储库的主要原因 + * `应该用宽泛的术语来描述模块,一般只在几段中;模块的例程或方法、冗长的代码示例或其他深入的材料的更多细节应该在后面的章节中给出。` + + `理想情况下,稍微熟悉模块的人应该能够刷新他们的内存,而不必点击“向下翻页”。当读者继续阅读文档时,他们应该会逐渐获得更多的知识。` + + ~[Kirrily "Skud" Robert, perlmodstyle](http://perldoc.perl.org/perlmodstyle.html) + +### 内容列表 + +* 状态:必须;对于小于`100`行的`README`是可选的 +* 必要条件: + * 必须链接到文件中的所有markdown章节 + * 必须从第二节开始;不要包含标题或目录标题 + * 必须至少有一个深度:必须捕获所有二级标题(`##`) +* 建议: + * 可以捕获三级(`###`)和四级(`####`)深度的标题。如果是长目录,这些是可选的 + +### 安全 + +* 状态:可选 +* 必要条件: + * 如果有必要强调安全问题,则说明。否则,它应该在`Extra Sections` + +### 背景 + +* 状态:可选 +* 必要条件: + * 涵盖动机 + * 覆盖抽象依赖项 + * 涵盖知识来源:`see also`也很合适 + +### 安装 + +* 状态:默认是必须的,对于文档仓库而言是可选的 +* 必要条件: + * 使用代码块说明如何安装 +* 子章节(`subsections`): + * 依赖(`dependencies`):如果有不寻常的依赖项或依赖项必须手动安装,必须提出 +* 建议: + * 链接到编程语言的必备站点:[npmjs](https://npmjs.com/)、[godocs](https://godoc.org/)等 + * 包括安装所需的任何系统特定信息 + * 增加一个`updating`章节是有用的 + +### 用法 + +* 状态:默认是必须的,对于文档仓库而言是可选的 +* 必要条件: + * 使用代码块说明常见用法 + * 如果兼容于`cli`,用代码块说明其用法 + * 如果可导入,用代码块表示导入功能和用法 +* 子章节: + * `CLI`:如果命令行功能存在则是必要的 +* 建议: + * 覆盖可能影响使用的基本选项:例如,如果是`javascript`,则覆盖`promises/callbacks`(对`ES6`而言) + * 可以指向示例代码的可执行文件 + +### 附加内容 + +* 状态:可选 +* 必要条件: + * 无 +* 建议: + * 这不应称为附加内容。可容纳`0`个或多个章节,每个章节必须有其标题 + * 这应该包含任何其他相关的内容,放在用法之后,应用程序接口之前 + * 具体来说,如果安全章节不够重要,不需要放在上面的话,可以放在这里 + +### 应用编程接口 + +* 状态:可选 +* 必要条件: + * 描述开放的函数和对象 +* 建议: + * 描述签名、返回类型、回调和事件 + * 覆盖类型不明显的地方 + * 描述注意事项 + * 如果使用外部`api`生成器(如`go-doc、js-doc`等),那么指向外部`api.md`文件即可 + +### 主要维护人员 + +* 状态:可选 +* 必要条件: + * 列出存储库的维护人员,以及联系他们的一种方式(例如`github`链接或电子邮件) +* 建议: + * 这应该是一个负责这个仓库人员的小名单。这不应该是所有拥有访问权限的人,例如整个组织,而是应该`ping`并负责管理和维护存储库的人 + * 列出过去的维护者是友好的 + +### 致谢 + +* 状态:可选 +* 必要条件: + * 必须称为`Thanks, Credits`和`Acknowledgements`的其中一种 +* 建议: + * 陈述任何对项目开发有重大帮助的人或事 + * 列出公共联系人的超链接(如果可以的话) + +### 参与贡献方式 + +* 状态:必须 +* 必要条件: + * 说明用户可在哪里提问 + * 说明是否接受`PR` + * 列出参与的任何要求;例如,对提交进行审核 +* 建议: + * 如果有的话,链接到`CONTRIBUTING`文件 + * 尽可能友好 + * 链接到`github`问题库 + * 链接到行为准则(`Code of Conduct`)。`Coc`通常位于贡献部分或文档中,或者设置在整个组织的其他位置,因此可能不需要在每个存储库中包含整个文件。但是,强烈建议始终链接到代码,无论它位于何处 + * 也可以在这里增加一个小节,列出贡献者 + +### 许可证 + +* 状态:必须 +* 必要条件: + * 列出许可证全名或标识符,参考[`SPDX`许可证列表](https://spdx.org/licenses/)。对于未授权的存储库,添加标识`UNLICENSED`。对于许可证的详细信息,添加`see license in `并链接到许可文件。(参考[npm](https://docs.npmjs.com/files/package.json#license)设置) + * 列出许可证拥有者 + * 必须是最后一节 +* 建议: + * 链接到本地存储库中较长的许可证文件 + +## 定义 + +*提供这些定义是为了理清上述使用的任何术语* + +* 文档仓库(`Documentation repositories`):仓库中没有任何功能代码,比如[RichardLitt/knowledge](https://github.com/RichardLitt/knowledge) \ No newline at end of file diff --git a/docs/tool/generator-standard-readme.md b/docs/tool/generator-standard-readme.md new file mode 100644 index 0000000..95672bc --- /dev/null +++ b/docs/tool/generator-standard-readme.md @@ -0,0 +1,113 @@ + +# README生成器 + +[RichardLitt/generator-standard-readme](https://github.com/RichardLitt/generator-standard-readme)提供了一个`npm`命令行工具,用于生成`README`文件 + +## 安装 + +``` +npm install --global yo generator-standard-readme +``` + +## 使用 + +命令行输入 + +``` +$ yo standard-readme +``` + +接下来会提出很多问题,然后生成一个README文件。所有问题如下: + +``` +What do you want to name your module? +What is the description of this module? +Do have a banner image? + Where is the banner image? Ex: 'img/banner.png' +Do you want a TODO dropped where your badges should be? +Do you want a TODO dropped where your long description should be? +Do you need a prioritized security section? +Do you need a background section? +Do you need an API section? +What is the GitHub handle of the main maintainer? +Do you have a CONTRIBUTING.md file? +Are PRs accepted? +Is an MIT license OK? + What is your license? +Who is the License holder (probably your name)? +Use the current year? + What years would you like to specify? +``` + +## 示例 + +``` +$ yo standard-readme +? ========================================================================== +We're constantly looking for ways to make yo better! +May we anonymously report usage statistics to improve the tool over time? +More info: https://github.com/yeoman/insight & http://yeoman.io +========================================================================== Yes +? What is the name of your module? zj +? What is the description of this module? yo使用示例 +? Do have a banner image? No +? Do you want a standard-readme compliant badge? Yes +? Do you want a TODO dropped where more badges should be? Yes +? Do you want a TODO dropped where your long description should be? Yes +? Do you need a prioritized security section? No +? Do you need a background section? Yes +? Do you need an API section? No +? What is the GitHub handle of the main maintainer? zjZSTU +? Do you have a CONTRIBUTING.md file? No +? Are PRs accepted? Yes +? Is an MIT license OK? Yes +? Who is the License holder (probably your name)? zjZSTU +? Use the current year? Yes + create README.md +``` + +生成文件如下: + + # zj // 标题 + + [![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) // 徽章 + TODO: Put more badges here. // 可以添加更多徽章 + + > yo使用示例 // 简短说明 + + TODO: Fill out this long description. // 详细说明 + + ## Table of Contents // 下面的章节列表,每个章节都可以点击跳转 + + - [Background](#background) + - [Install](#install) + - [Usage](#usage) + - [Maintainers](#maintainers) + - [Contributing](#contributing) + - [License](#license) + + ## Background // 背景 + + ## Install // 安装 + + ``` + ``` + + ## Usage // 用法 + + ``` + ``` + + ## Maintainers // 主要维护人员 + + [@zjZSTU](https://github.com/zjZSTU) + + ## Contributing // 参与贡献方式 + + PRs accepted. + + Small note: If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. + + ## License // 许可证 + + MIT © 2019 zjZSTU \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 77b85f2..daaf19e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -37,4 +37,9 @@ extra_javascript: # 导航 nav: - - Home: index.md \ No newline at end of file + - Home: index.md + - 规范: + - README: + - 引言: readme/index.md + - '[译]规范': readme/译-规范.md + - '徽章': readme/badge.md \ No newline at end of file diff --git a/templates/CHANGELOG b/templates/CHANGELOG new file mode 100644 index 0000000..e69de29 diff --git a/templates/LICENSE b/templates/LICENSE new file mode 100644 index 0000000..261eeb9 --- /dev/null +++ b/templates/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/templates/MINIMAL_README.md b/templates/MINIMAL_README.md new file mode 100644 index 0000000..a869eed --- /dev/null +++ b/templates/MINIMAL_README.md @@ -0,0 +1,36 @@ +# PyNet + +[中文版本(Chinese version)](./MINIMAL_README.zh-CN.md) + +> Numpy-based deep learning library + +## Table of Contents + +- [Install](#install) +- [Usage](#usage) +- [Contributing](#contributing) +- [License](#license) + +## Install + +``` +``` + +## Usage + +``` +``` + +## Contributing + +PRs accepted. + +Small note: + +* Git submission specifications should be complied with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) +* If versioned, please conform to the [Semantic Versioning 2.0.0](https://semver.org) specification +* If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. + +## License + +[Apache License 2.0](LICENSE) © 2019 zjZSTU diff --git a/templates/MINIMAL_README.zh-CN.md b/templates/MINIMAL_README.zh-CN.md new file mode 100644 index 0000000..333d007 --- /dev/null +++ b/templates/MINIMAL_README.zh-CN.md @@ -0,0 +1,36 @@ +# PyNet + +[英文版本(English version)](./MINIMAL_README.md) + +> 基于numpy的深度学习库 + +## 内容列表 + +- [安装](#安装) +- [用法](#用法) +- [参与贡献方式](#参与贡献方式) +- [许可证](#许可证) + +## 安装 + +``` +``` + +## 用法 + +``` +``` + +## 参与贡献方式 + +接受合并请求 + +请注意: + +* git提交请遵守[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) +* 如果进行版本化,请遵守[Semantic Versioning 2.0.0](https://semver.org)规范 +* 如果修改README,请遵守[standard-readme](https://github.com/RichardLitt/standard-readme)规范 + +## 许可证 + +[Apache License 2.0](LICENSE) © 2019 zjZSTU diff --git a/templates/STANDARD_README.md b/templates/STANDARD_README.md new file mode 100644 index 0000000..e10dc81 --- /dev/null +++ b/templates/STANDARD_README.md @@ -0,0 +1,111 @@ +# PyNet + +![](logo.png) + +[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) + +[中文版本(Chinese version)](./STANDARD_README.zh-CN.md) + +> Numpy-based deep learning library + +Implementation of deep learning based on numpy, modular design guarantees easy implementation of the model, which is suitable for the introduction of junior researchers in deep learning. + +## Table of Contents + +- [Background](#background) +- [Badge](#badge) +- [Install](#install) +- [Usage](#usage) +- [CHANGELOG](#CHANGELOG) +- [TODO](#todo) +- [Maintainers](#maintainers) +- [Thanks](#Thanks) +- [Contributing](#contributing) +- [License](#license) + +## Background + +Systematic learning convolution neural network has been nearly half a year.Using librarys such as pytorch can't understand the implementation in depth. So I plan to complete a deep learning framework from scratch.The initial implementation will refer to the operation of cs231n, and then we will implement it in the form of computational graphs. I hope this project can improve my programming ability and help others at the same time. + +## Badge + +If you use PyNet, add the following Badge + +[![pynet](https://img.shields.io/badge/pynet-ok-brightgreen)](https://github.com/zjZSTU/PyNet) + +To add in Markdown format, use this code: + +``` +[![pynet](https://img.shields.io/badge/pynet-ok-brightgreen)](https://github.com/zjZSTU/PyNet) +``` + +## Install + +PyNet need the following prerequisites + +* python3.x +* numpy +* opencv3.x + +## Usage + +Refer to the sample code under the [example](https://github.com/zjZSTU/PyNet/tree/master/examples) folder + +Full version reference [releases](https://github.com/zjZSTU/PyNet/releases) + +Realized Network Model(Located in [pynet/models](https://github.com/zjZSTU/PyNet/tree/master/pynet/models) folder): + +* 2-Layer Neural Network +* 3-Layer Neural Network +* LeNet-5 +* AlexNet +* NIN + +Realized Network Layer(Located in [pynet/nn](https://github.com/zjZSTU/PyNet/tree/master/pynet/nn) folder): + +* Convolution Layer (Conv2d) +* Fully-Connected Layer (FC) +* Max-Pooling layer (MaxPool) +* ReLU Layer (ReLU) +* Random Dropout Layer (Dropout/Dropout2d) +* Softmax +* Cross Entropy Loss +* Gloabl Average Pool (GAP) + +## CHANGELOG + +see the [CHANGELOG](./CHANGELOG) on this repository. + +## TODO + +* Realization of batch normalization +* Realization of Computational Graph + +## Maintainers + +* zhujian - *Initial work* - [zjZSTU](https://github.com/zjZSTU) + +## Thanks + +Thank you for your participation. + +[![](https://avatars3.githubusercontent.com/u/13742735?s=460&v=4)](https://github.com/zjZSTU) + +Refer to the following Library + +* [cs231n](http://cs231n.github.io/) +* [PyTorch](https://pytorch.org/) + +## Contributing + +Anyone's participation is welcome! Open an [issue](https://github.com/zjZSTU/PyNet/issues) or submit PRs. + +Small note: + +* Git submission specifications should be complied with [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) +* If versioned, please conform to the [Semantic Versioning 2.0.0](https://semver.org) specification +* If editing the README, please conform to the [standard-readme](https://github.com/RichardLitt/standard-readme) specification. + +## License + +[Apache License 2.0](LICENSE) © 2019 zjZSTU diff --git a/templates/STANDARD_README.zh-CN.md b/templates/STANDARD_README.zh-CN.md new file mode 100644 index 0000000..c773357 --- /dev/null +++ b/templates/STANDARD_README.zh-CN.md @@ -0,0 +1,112 @@ + +# PyNet + +![](logo.png) + +[![standard-readme compliant](https://img.shields.io/badge/standard--readme-OK-green.svg?style=flat-square)](https://github.com/RichardLitt/standard-readme) [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg)](https://conventionalcommits.org) [![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/) + +[英文版本(English version)](./STANDARD_README.md) + +> 基于Numpy的深度学习库 + +基于`Numpy`的深度学习实现,模块化设计保证模型的轻松实现,适用于深度学习初级研究人员的入门 + +## 内容列表 + +- [背景](#背景) +- [徽章](#徽章) +- [安装](#安装) +- [用法](#用法) +- [版本更新日志](#版本更新日志) +- [待办事项](#待办事项) +- [主要维护人员](#主要维护人员) +- [致谢](#致谢) +- [参与贡献方式](#参与贡献方式) +- [许可证](#许可证) + +## 背景 + +系统性的学习卷积神经网络也快半年了,使用`pytorch`等库不能很好的深入理解实现,所以打算从头完成一个深度学习框架。最开始的实现会参考`cs231n`的作业,之后会以计算图的方式实现。希望这个项目能够切实提高自己的编程能力,同时也能够帮助到其他人 + +## 徽章 + +如果你使用了`PyNet`,请添加以下徽章 + +[![pynet](https://img.shields.io/badge/pynet-ok-brightgreen)](https://github.com/zjZSTU/PyNet) + +Markdown格式代码如下: + +``` +[![pynet](https://img.shields.io/badge/pynet-ok-brightgreen)](https://github.com/zjZSTU/PyNet) +``` + +## 安装 + +`PyNet`需要以下必备条件 + +* `python3.x` +* `numpy` +* `opencv3.x` + +## 用法 + +参考[example](https://github.com/zjZSTU/PyNet/tree/master/examples)文件夹下的示例代码 + +完整版本参考[releases](https://github.com/zjZSTU/PyNet/releases) + +已实现网络模型(位于[pynet/models](https://github.com/zjZSTU/PyNet/tree/master/pynet/models)文件夹): + +* `2`层神经网络 +* `3`层神经网络 +* `LeNet-5` +* `AlexNet` +* `NIN` + +已实现网络层(位于[pynet/nn](https://github.com/zjZSTU/PyNet/tree/master/pynet/nn)文件夹): + +* 卷积层 +* 全连接层 +* 最大池化层 +* `ReLU` +* 随机失活 +* `Softmax` +* 交叉熵损失 +* 全局平均池化层 + +## 版本更新日志 + +请参阅仓库中的[CHANGELOG](./CHANGELOG) + +## 待办事项 + +* 批量归一化实现 +* 计算图实现 + +## 主要维护人员 + +* zhujian - *Initial work* - [zjZSTU](https://github.com/zjZSTU) + +## 致谢 + +感谢以下人员的参与 + +[![](https://avatars3.githubusercontent.com/u/13742735?s=460&v=4)](https://github.com/zjZSTU) + +参考以下库 + +* [cs231n](http://cs231n.github.io/) +* [PyTorch](https://pytorch.org/) + +## 参与贡献方式 + +欢迎任何人的参与!打开[issue](https://github.com/zjZSTU/PyNet/issues)或提交合并请求。 + +注意: + +* `git`提交请遵守[Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0-beta.4/) +* 如果进行版本化,请遵守[Semantic Versioning 2.0.0](https://semver.org)规范 +* 如果修改README,请遵守[standard-readme](https://github.com/RichardLitt/standard-readme)规范 + +## 许可证 + +[Apache License 2.0](LICENSE) © 2019 zjZSTU diff --git a/templates/logo.png b/templates/logo.png new file mode 100644 index 0000000..fd4a17a Binary files /dev/null and b/templates/logo.png differ