python项目结构示例

Documenting Your Python Projects

Python项目以各种形式、大小和目的出现。您文档化项目的方式应该适合您的特定情况。记住项目的用户将是谁，并根据他们的需求进行调整。根据项目类型，建议对文档的某些方面进行处理。项目及其文档的一般布局应如下所示：

project_root/
│
├── project/  # 项目源代码
├── docs/
├── README
├── HOW_TO_CONTRIBUTE
├── CODE_OF_CONDUCT
├── examples.py
项目通常可以分为三种主要类型：私有、共享和公共/开源。
私有项目

私有项目是专为个人使用而设计的项目，通常不与其他用户或开发人员共享。这些类型的项目的文档可能相对简单。根据需要，可以添加一些推荐的部分：

Readme：对项目及其目的的简要概述。包括安装或操作项目的任何特殊要求。
examples.py：一个Python脚本文件，提供如何使用项目的简单示例。
请记住，尽管私有项目是为您个人使用的，但您也被视为用户。考虑到将来可能会有什么困惑，确保在注释、文档字符串或自述文件中捕获这些内容。

共享项目

共享项目是您与少数其他人在项目的开发和/或使用中进行合作的项目。“客户”或项目的用户仍然是您自己和那些少数人员使用项目的人员。

文档应该比私有项目需要的要严格一些，主要是为了帮助新成员加入项目或提醒贡献者/用户项目的新变化。建议添加到项目中的一些部分如下：

Readme：对项目及其目的的简要概述。包括安装或操作项目的任何特殊要求。另外，添加自上一个版本以来的任何重大更改。
examples.py：一个Python脚本文件，提供如何使用项目的简单示例。
如何贡献：这应该包括新贡献者如何开始贡献到项目中。
公共和开源项目

公共和开源项目是打算与大量用户分享的项目，可能涉及庞大的开发团队。这些项目应将项目文档的优先级放在与项目开发本身一样高。建议添加到项目中的一些部分如下：

Readme：对项目及其目的的简要概述。包括安装或操作项目的任何特殊要求。另外，添加自上一个版本以来的任何重大更改。最后，添加到进一步文档、错误报告和任何其他项目重要信息的链接。Dan Bader提供了一个很好的教程，说明应该在自述文件中包含的所有内容。

如何贡献：这应该包括新贡献者如何帮助项目。这包括开发新功能、修复已知问题、添加文档、添加新测试或报告问题。

行为准则：定义其他贡献者在开发或使用您的软件时应该如何对待彼此。还说明如果违反此代码会发生什么。如果您使用的是Github，则可以使用推荐的措辞生成行为准则模板。特别是对于开源项目，考虑添加此内容。

许可证：描述您的项目正在使用的许可证的纯文本文件。特别是对于开源项目，考虑添加此内容。

docs：包含进一步文档的文件夹。描述了应包含和如何组织此文件夹的内容。