编辑
2024-01-18
开源
0
请注意,本文编写于 38 天前,最后修改于 36 天前,其中某些信息可能已经过时。

目录

用一个项目做案例
代码的自动 CI 触发的结果
nuget package 发布的结果
mkdocs 生成文档
将你引用的源码的原始 license 文件放入你的代码中

看完本文会得到什么

  1. 为开源项目添加小徽章 Badge
  2. 使用 mkdocs 给自己的开源项目提供赏心悦目的文档
  3. 引用的开源代码的版权声明文件

用一个项目做案例

https://github.com/strapi-extensions/strapi-csharp-sdk

这个项目是我为 https://strapi.io/ 写的一个 c# 跨平台的 sdk,我在写它的时候充分参照 https://github.com/parse-community/Parse-SDK-dotNET 的项目,并且海量拷贝了可用代码,不愧是大神的作品,设计模式和编码习惯都极其优雅,十分赞叹。

我看到 Parse 的 GitHub 页面上有很多可爱的 bagde

image.png

因此我也想拥有这个,我就根据这些 badge 的地址挨个查找对应的配置方法。

常见的动态 badge 有如下几种

代码的自动 CI 触发的结果

例如你的代码在 main 分支上自动检测的 CI Pipeline 或者你有配置过 GitHub Actions,CI 服务供应商现在都会提供 badge 功能,方便我们快速的对 CI 结果进行展示和报错提示。

因为我充分信任并且热爱 GitHub Actions,我很快就通过搜索找到了这篇文档

https://docs.github.com/en/actions/monitoring-and-troubleshooting-workflows/adding-a-workflow-status-badge

根据我设置的 GitHub Actions 里面一个 workflow

https://github.com/strapi-extensions/strapi-csharp-sdk/blob/main/.github/workflows/nuget-publish.yml

根据文档我可以很快拼写出我自己的项目里面的 main 分支上对应的 action 的 badge

https://github.com/strapi-extensions/strapi-csharp-sdk/actions/workflows/nuget-publish.yml/badge.svg

加上 md 语法的渲染就会变成如下效果: publish status on main

nuget package 发布的结果

谷歌搜索 -> https://shields.io/

可以找到对应的官网,然后你在 https://shields.io/badges/nu-get-version 可以找到对应的 nuget 的配置方式

md 渲染效果如下:

mkdocs 生成文档

业界鼎鼎大名的 mkdocs 可能是生成指导性文档最好的工具,没有之一。当然还有一些其他静态网页生成工具,如果你更熟悉别的选择也可以。

将你引用的源码的原始 license 文件放入你的代码中

文件名不一定是license.txt,也有叫copying(mysql是这样的)、copyright、copyleft、license(无后缀)、开源协议名(xampp就是gpl.txt),甚至还有用html和pdf的。

如果你引用第三方的开源软件,版权文件可以这样放:

  1. 保留第三方软件自己的目录结构,在其根目录下一般就有版权声明文件
  2. 在你的软件根目录放置它的版权说明,如jsonTools_license.txt
  3. 如果你引用的第三方软件特别多,你也可以在你的软件根目录建一个文件夹,专门放你引用的各个开源软件的版权文件。