100-Days-Of-ML-Code项目文档生成：Sphinx与Read the Docs配置

100-Days-Of-ML-Code项目文档生成：Sphinx与Read the Docs配置

【免费下载链接】100-Days-Of-ML-Code 项目地址: https://gitcode.com/gh_mirrors/100d/100-Days-Of-ML-Code

项目概述

100-Days-Of-ML-Code是一个旨在帮助学习者系统掌握机器学习知识的开源项目，提供了从基础算法到深度学习的完整学习路径。项目包含丰富的代码实现、数据文件和学习资源，适合机器学习入门者和爱好者进行系统学习。

项目结构

项目主要包含以下几个部分：

• 代码实现：Code/目录下包含了各天的学习代码，包括Python文件和Jupyter Notebook
• 数据集：datasets/目录提供了学习过程中使用的各种数据文件
• 学习资源：Other Docs/目录包含了数据科学相关的学习资料和速查手册
• 信息图表：Info-graphs/目录提供了可视化的学习资料

Sphinx与Read the Docs简介

Sphinx文档生成工具

Sphinx是一个基于Python的文档生成工具，最初用于Python官方文档的编写，现在已被广泛应用于各种项目的文档生成。它支持reStructuredText和Markdown格式，能够生成HTML、PDF、EPUB等多种格式的文档。

Read the Docs托管服务

Read the Docs是一个免费的文档托管服务，可以自动从GitHub、GitLab等代码仓库拉取代码，使用Sphinx或MkDocs生成文档，并提供在线访问。它支持文档版本管理，能够为不同版本的项目提供对应的文档。

项目现有文档分析

现有文档结构

当前项目主要使用Markdown格式的文件作为文档，包括：

• 项目主文档：README.md
• 代码文档：如Code/Day 11_K-NN.md、Code/Day 13_SVM.md等
• 常见问题：FAQ.MD

现有文档示例

以支持向量机(SVM)的文档为例，现有文档包含算法实现和相关说明：

支持向量机实现

# 导入库
import numpy as np
import matplotlib.pyplot as plt
import pandas as pd

# 导入数据集
dataset = pd.read_csv('Social_Network_Ads.csv')
X = dataset.iloc[:, [2, 3]].values
y = dataset.iloc[:, 4].values

# 拆分数据集为训练集和测试集
from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size = 0.25, random_state = 0)

# 特征缩放
from sklearn.preprocessing import StandardScaler
sc = StandardScaler()
X_train = sc.fit_transform(X_train)
X_test = sc.transform(X_test)

# 拟合SVM到训练集
from sklearn.svm import SVC
classifier = SVC(kernel = 'linear', random_state = 0)
classifier.fit(X_train, y_train)

# 预测测试集结果
y_pred = classifier.predict(X_test)

# 创建混淆矩阵
from sklearn.metrics import confusion_matrix
cm = confusion_matrix(y_test, y_pred)

# 可视化训练集结果
from matplotlib.colors import ListedColormap
X_set, y_set = X_train, y_train
X1, X2 = np.meshgrid(np.arange(start = X_set[:, 0].min() - 1, stop = X_set[:, 0].max() + 1, step = 0.01),
                     np.arange(start = X_set[:, 1].min() - 1, stop = X_set[:, 1].max() + 1, step = 0.01))
plt.contourf(X1, X2, classifier.predict(np.array([X1.ravel(), X2.ravel()]).T).reshape(X1.shape),
             alpha = 0.75, cmap = ListedColormap(('red', 'green')))
plt.xlim(X1.min(), X1.max())
plt.ylim(X2.min(), X2.max())
for i, j in enumerate(np.unique(y_set)):
    plt.scatter(X_set[y_set == j, 0], X_set[y_set == j, 1],
                c = ListedColormap(('red', 'green'))(i), label = j)
plt.title('SVM (Training set)')
plt.xlabel('Age')
plt.ylabel('Estimated Salary')
plt.legend()
plt.show()

算法可视化资源

项目提供了丰富的算法可视化资源，帮助理解各种机器学习算法的原理和应用。例如：

SVM算法可视化


决策树算法可视化


随机森林算法可视化


Sphinx文档配置指南

安装Sphinx

首先需要安装Sphinx及其相关扩展：

pip install sphinx sphinx-rtd-theme sphinx-markdown-builder

初始化Sphinx项目

在项目根目录下执行以下命令初始化Sphinx文档项目：

mkdir docs
cd docs
sphinx-quickstart

根据提示进行配置，主要设置包括：

• 项目名称：100-Days-Of-ML-Code
• 作者名称：MachineLearning100
• 项目版本：1.0
• 文档语言：zh_CN

配置Sphinx

编辑docs/conf.py文件，进行以下配置：

# 添加项目根目录到路径
import os
import sys
sys.path.insert(0, os.path.abspath('..'))

# 扩展
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.napoleon',
    'sphinx.ext.viewcode',
    'm2r2',
]

# 主题
html_theme = 'sphinx_rtd_theme'

# 支持Markdown文件
source_suffix = ['.rst', '.md']

# 自动生成API文档
autodoc_default_options = {
    'members': True,
    'undoc-members': True,
    'show-inheritance': True,
}

编写Sphinx文档

创建docs/index.rst文件作为文档入口：

.. 100-Days-Of-ML-Code documentation master file, created by
   sphinx-quickstart on Wed Oct  8 08:02:01 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

100-Days-Of-ML-Code 文档
=========================

欢迎来到100-Days-Of-ML-Code项目的文档。这个项目提供了机器学习从基础到进阶的完整学习路径。

.. toctree::
   :maxdepth: 2
   :caption: 目录:

   introduction
   installation
   day1
   day2
   ...

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Read the Docs配置

创建.readthedocs.yml文件

在项目根目录创建.readthedocs.yml文件：

version: 2

sphinx:
  configuration: docs/conf.py

python:
  version: 3.8
  install:
    - requirements: docs/requirements.txt

创建requirements.txt文件

在docs/目录下创建requirements.txt文件，列出文档构建所需的依赖：

sphinx==4.2.0
sphinx-rtd-theme==1.0.0
sphinx-markdown-builder==0.5.4
m2r2==0.3.2
numpy==1.21.2
pandas==1.3.3
scikit-learn==0.24.2

在Read the Docs上托管文档

1. 登录Read the Docs网站，使用GitHub账号授权
2. 导入100-Days-Of-ML-Code项目
3. 配置项目设置，指定文档构建配置文件路径
4. 触发文档构建，等待构建完成

文档自动生成

从Markdown文件生成文档

可以使用sphinx-markdown-builder从现有的Markdown文件生成Sphinx文档：

cd docs
make markdown

自动生成API文档

使用sphinx-apidoc工具从Python代码自动生成API文档：

sphinx-apidoc -o docs/source Code/

项目资源推荐

数据科学速查手册

项目提供了丰富的数据科学速查手册，帮助快速查阅各种库和工具的使用方法：

数据科学速查手册

Python数据科学手册

项目包含《Python数据科学手册》的中文版PDF，是学习Python数据科学的优质资源：

Python数据科学手册

算法实现代码

各天的学习代码实现：

• K-NN算法
• SVM算法
• 决策树算法
• 随机森林算法

总结与展望

通过Sphinx和Read the Docs可以为100-Days-Of-ML-Code项目构建专业、易读的文档，方便学习者查阅和理解各个机器学习算法的实现和应用。未来可以进一步完善文档内容，增加更多示例和解释，提高文档的实用性和可读性。

项目目前已经积累了丰富的学习资源和代码实现，通过系统化的文档组织，可以更好地发挥这些资源的价值，帮助更多人入门和掌握机器学习知识。

如何贡献

如果您有兴趣为项目文档贡献力量，可以：

1. 改进现有代码的注释
2. 编写更详细的算法解释
3. 补充示例代码和应用场景
4. 完善文档结构和内容

详细贡献指南请参考项目README。

【免费下载链接】100-Days-Of-ML-Code 项目地址: https://gitcode.com/gh_mirrors/100d/100-Days-Of-ML-Code