python 创建工具包
并非每个网站都是博客,博客的主要功能是帖子列表,每个帖子都有特定的时间戳,以指示其“新鲜度”。 有时,您只想要一个网站 。
也许您是一名业余(或专业!)厨师,并且想炫耀自己的食谱。 也许您是一位诗人,并且想要一个网站发布您所有的诗。 也许您有很强的见解,并希望有一个地方来存储您的蚂蚁,每个蚂蚁都是永恒的完美。 这是狮身人面像进来的地方。
建立一个Sphinx网站
工程师们正在努力构建最低限度的可行产品,并且营销需要建立一个有吸引力的网站来展示该解决方案。 没有可用的工程资源,因为所有人都致力于解决乘法和求反问题,并且预算很少,您该怎么办?
故事从本地Git存储库开始,以便对网站进行版本控制 。
像所有好的Git存储库一样,该库以.gitignore开头,它告诉Git忽略其中列出的文件或目录。 这是一个简单,不起眼的.gitignore :
/build
我将解释为什么要将这个目录添加到下面的.gitignore文件中。
接下来,是时候让广告撰写人开始撰写市场营销副本了。 在doc / index.rst中 ,他们编写格式正确的reStructuredText :
Calculate Solutions
-------------------
Learn how to add, subtract, multiply, and divide!
.. toctree::
multiplication
negation
标点符号的使用和toctree的使用使我们可以创建要构建的子页面的目录。 接下来,我们可以在doc / multiplication.rst和doc / negation.rst中放置有关Calculate Solutions特定产品的更多详细信息。
然后添加一个简短的文件doc / conf.py ,其中包含重要的元数据:
master_doc
=
'index'
project
=
"Calculate.Solutions"
copyright
=
'2020, Calculate Solutions, Inc.'
author
=
'Calculate Solutions, Inc.'
version
= release
=
''
并设置版本并将其发布为空字符串。 Sphinx的最初目的是记录软件,这是一个用例,其中版本和发行标签很重要,但对Calculate Solutions的网站没有用。
最后,请确保您可以在本地生成文档,并确定它看起来不错。 为此,请使用方便的自动化和测试库tox 。
将以下tox配置文件保存到tox.ini中 :
[ tox ]
envlist
=
website
toxworkdir
=
{ toxinidir } /build/tox
skipsdist
=
True
[ testenv:website ]
basepython
=
python3.7
deps
=
sphinx
changedir
=
doc
commands
=
sphinx-build -W -b html -d
{ envtmpdir
} /doctrees .
{ envtmpdir
} /html
Tox配置分为两部分:一是常规配置,一是设置特定的“测试环境”。 常规配置设置测试环境列表; 在这里,您只有一个,一个在本地构建您的网站。 您还必须配置工作目录。 这很有用,因为默认情况下,tox会将其输出放入.tox目录中。 有时很难从Web浏览器之类的GUI程序中打开这样的“隐藏”目录。 因此,将其放在build下,即您在.gitignore中要忽略的目录。
默认情况下,tox假定您正在测试Python软件包。 由于您不是,所以将其告知skipsdist 。
在环境配置中,明确说明要使用哪个Python解释器。 Tox有时会尝试从环境名称中推断出这一点,但是在这种情况下,检测无法正常工作。 确保您在此处设置的版本在您的路径中可用。
从那里,告诉tox 将Sphinx安装在它为此运行创建的虚拟环境中,然后转到您的doc目录,在其中放置您的配置和市场营销副本,并运行用于构建网站的sphinx命令。
现在您可以简单地运行:
$ tox
成功运行后,在浏览器中打开build / docs / tmp / html / index.html以查看它是否正常。
发布您的网站
现在,您需要使您的网站脱离本地开发,走向世界! 您可以创建一个CI / CD管道 ,该管道将自动刷新并推出它,设置负载均衡器,并设置HTTPS证书,但这似乎需要大量工作。
输入阅读文档 。 Read the Docs是一个免费的网站,可以自动发布基于Sphinx的文档,并且都是由非常有思想的维护者使用开源软件构建的。
创建或登录您的“阅读文档”帐户后,进入“导入”屏幕。
您可能必须刷新您的帐户或项目列表,但是最终,您应该在选项列表中看到您的项目。
您不需要任何“高级”选项,因此请接受默认设置并继续。
单击“构建”按钮开始构建,您的第一个文档构建应开始:
第一个构建应该添加webhook来连接您的Git存储库以发布到“阅读文档”。 如果遇到问题,有足够的文档说明如何手动添加它。
构建完成后,您的网站启动了!
但是,您希望它在您的实际域上 calculate.solutions 。
为此,请使用“阅读文档”上的“自定义域”功能。
最后,您的网站已准备好公开发布。
尽管您是一家颠覆性的初创公司,但您仍在努力支持开源服务,因此请将您的帐户升级为金牌,然后将无广告选项应用于您的网站。
这也使您的网站看起来更专业!
无操作网站
如果您的食谱,诗歌,朗诵或“计算即服务”创业公司需要一个网站,则可以使用Sphinx和Read The Docs轻松访问网站。 将站点与最低的tox和Sphinx配置相结合,您便拥有了可扩展的基础结构,而您不必自己运行。 成功!
python 创建工具包