使用免费托管和域快速发布 Python 文档的方法

如果您对在线发布项目的 wiki、教程或文档感兴趣,您可能会面临安装和设置功能齐全的 CMS(如 WordPress)或学习 HTML、JavaScript 以及 Web 框架的问题。

AI吧Python

我想向您展示另一种选择,您可以在其中简单地基于降价创建一个网站并将其发布在免费的虚拟主机上。作为奖励,我将向您展示如何申请像my-project.py.wiki这样的免费域。

将降价促销变成网站

首先,我们需要能够将降价促销转化为静态网页内容的软件。该软件称为静态站点生成器。以我个人的经验,MkDocs是 python 用户最直接的选择。但是,还有其他值得注意的选项,例如SphinxPelican

让我们开始:

pip install mkdocs
mkdocs new my-great-project
cd my-great-project
ls -R

该文件夹应如下所示:

mkdocs.yml    # The configuration file.
docs/         # contains all the markdowns
    index.md

现在您可以将所有降价代码移动到文件夹docs。事实上,开发服务器支持自动重新加载,这意味着它会检测到降价更改并自动刷新页面。让我们使用mkdocs serve启动 dev-server 。对index.md进行一些更改并保存。

配置文件只有两个必填字段site_namesite_url。通过添加nav字段,您可以指定导航项的顺序和名称。开箱即用甚至支持分层导航。最后一个字段site_dir定义了网站的生成位置。以后会有用的。

site_name: Foo Docs
site_url: https://foo.py.wiki/
nav:
  - Home: index.md
  - Dev Guide:
      - Setup: setup.md
      - Bug Report: bug_report.md
site_dir: public/

让我们生成它,文件夹public现在应该包含一些静态文件。

mkdocs build
ls public/

如果您想知道py.wiki正在使用哪个主题,它是mkdocs-material。更多自定义主题可以在这里MkDocs Wiki: Themes找到。

在 GitLab 上托管您的文档

GitLab 提供了一项名为GitLab Pages的服务,可以直接从 GitLab 存储库发布静态网站。作为替代方案,您也可以使用Github PagesCloudflare Pages

在初始化 git 存储库之前,请在.gitignore中添加以下行,这样构建文件就不会被跟踪。

site/
public/

我们需要 CI/CD 环境的文件requirements.txt

echo 'mkdocs==1.3.0' > requirements.txt

GitLab 有一个内置的 CI/CD 服务。我们现在必须配置此服务,以便 MkDocs 在部署阶段在public文件夹中生成网站。

让我们在根文件夹中创建一个文件.gitlab-ci.yml,如下所示:

image: python:3.10-bullseye

stages:
  - deploy

before_script:
  - pip install -r requirements.txt

pages:
  stage: deploy
  script:
    - mkdocs build --verbose
  artifacts:
    paths:
      - public

现在,随着远程分支上的每次推送,我们的文档都被构建和发布。第一次构建后,您的网站应该在https://{username}.gitlab.io/{project-name}.

如果您更喜欢手动触发构建过程,可以添加以下行:

  ...
  artifacts:
    paths:
      - public
  when: manual # <---- add this line

CI/CD菜单转到Pipelines,您将看到此管道已被跳过。如果您点击舞台,您就有可能开始这个舞台。

CI阶段细节

声称一个时尚的域名

当我遇到带有域的 JavaScript 库时*.js.org,我注意到域是多么容易记住。就个人而言,我发现js.org为 JavaScript 社区提供了很好的服务,所以我想为 Python 社区做一些类似的事情。

这就是我创建服务的方式py.wiki,人们可以在其中注册*.py.wiki Python 相关项目的域。

想一个合适的域。以下是有关如何确定适当域名的一些想法:

  • 如果库“foo-bar”=> foo-bar.py.wiki
  • 如果库“foopy”=> foo.py.wiki
  • 如果 gitlab 页面 “foo.github.io/bar” => foo.py.wiki
  • 如果 gitlab 页面 “foo.github.io/bar” => bar.py.wiki

转到“设置”菜单中的“页面” ,然后单击“新域”。输入您想要的域名。单击Create New Domain后,将显示DNS验证状态字段。记住这些信息。

GitLab 页面 – 新域

让我们分叉存储库py.wiki。我们必须扩展文件dns_config.yml。有两种方法可以在 CNAME 下添加我们的域。第一种方法会自动启用 Cloudflare 代理,这意味着 Cloudflare 将缓存您网站的内容。

CNAME:
  py.wiki: bigaru.gitlab.io

如果您不希望缓存您的内容,您可以禁用 Cloudflare 代理,如下所示:

CNAME:
  py.wiki:
    name: bigaru.gitlab.io
    proxied: false

按字母顺序插入您的域:

CNAME:
  foo.py.wiki: foo.gitlab.io
  py.wiki: bigaru.gitlab.io
  www.py.wiki:
    name: bigaru.gitlab.io
    proxied: true

对于 GitLab Pages,我们还需要添加 TXT 记录来验证所有权。因此,只需将您的条目附加到 TXT:

TXT:
  _gitlab-pages-verification-code.py.wiki: gitlab-pages-verification-code=0000
  _gitlab-pages-verification-code.www.py.wiki: gitlab-pages-verification-code=0000
  _gitlab-pages-verification-code.foo.py.wiki: gitlab-pages-verification-code=0000

保存并推送到远程分支后,让我们打开一个新的合并请求。选择模板“新域”。之后,填写表格并创建合并请求。

一旦您的合并请求被接受并合并,CI 服务器将自动更新 Cloudflare 上的 DNS 记录。DNS 试用期可能需要一些时间。此后,您的页面将可以在一个花哨的域下访问。

发表评论

邮箱地址不会被公开。 必填项已用*标注