本地Read the Docs构建：如何开放文档访问并启用特色项目功能？

我之前也在私有部署的RTD环境里折腾过这个功能，确实官方文档没把这个点写得很直白，下面是我亲测有效的步骤：

1. 先确认你的Read the Docs版本 #

「特色项目」的配置逻辑在RTD社区版（readthedocs-community）的不同版本里有差异，先检查下你的部署版本：

# 在RTD服务器的虚拟环境中执行，查看版本
pip show readthedocs-community

如果是v5.x及以上版本，配置会更简洁；旧版本可能需要额外调整模板文件。

2. 修改核心配置文件 #

找到你部署目录下的settings.py（通常在/opt/readthedocs/或者虚拟环境的site-packages/readthedocs/路径下），添加或调整以下配置项：

• 启用特色项目功能：

  # 开启首页的特色项目板块
  FEATURED_PROJECTS_ENABLED = True
  # 设置展示的特色项目数量，默认是3个，可按需修改
  FEATURED_PROJECTS_COUNT = 3
  

• 确保未登录用户能访问文档：
  结合你提到的「所有用户无论是否登录都能看到文档」的需求，还要补充这两个全局配置：

  # 允许未登录用户访问所有公开项目的文档
  PUBLIC_DOCS = True
  # 允许未登录用户浏览公开项目列表
  PUBLIC_PROJECTS = True
  

  另外，每个开发者创建的项目，需要在后台将其隐私设置改为「Public」，才能被未登录用户看到。

3. 在后台指定特色项目 #

配置完后，需要手动标记哪些项目是「特色项目」：

• 登录RTD的管理员后台（访问/admin/路径）
• 进入Projects菜单，打开你想设为特色的项目详情页
• 在「Advanced settings」（高级设置）里，找到「Featured project」选项，勾选后保存即可

如果需要批量设置多个项目，也可以直接操作数据库（以PostgreSQL为例）：

-- 替换成你要设置的项目slug
UPDATE projects_project SET is_featured = true WHERE slug IN ('project-a', 'project-b');

4. 清理缓存并重启服务 #

修改配置和数据库后，必须清理缓存并重启服务才能生效：

# 清理Django缓存
python manage.py clearcache
# 根据你的部署方式重启服务，比如用systemd管理的话
sudo systemctl restart readthedocs

5. 自定义特色项目展示样式（可选） #

如果想调整首页特色项目的布局或样式，可以修改RTD的模板文件：

• 找到模板目录下的homepage.html（通常在readthedocs/templates/homepage.html）
• 定位到featured-projects相关的HTML区块，按需调整结构或添加自定义CSS

内容的提问来源于stack exchange，提问作者Innerhippy