mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
58 lines
2.6 KiB
ReStructuredText
58 lines
2.6 KiB
ReStructuredText
|
Deploying a Sphinx project online
|
||
|
|
=================================
|
||
|
|
|
||
|
|
When you are ready to show your documentation project to the world, there are
|
||
|
|
many options available to do so. Since the HTML generated by Sphinx is static,
|
||
|
|
you can decouple the process of building your HTML documentation from hosting
|
||
|
|
such files in the platform of your choice. You will not need a sophisticated
|
||
|
|
server running Python: virtually every web hosting service will suffice.
|
||
|
|
|
||
|
|
Therefore, the challenge is less how or where to serve the static HTML, but
|
||
|
|
rather how to pick a workflow that automatically updates the deployed
|
||
|
|
documentation every time there is a change in the source files.
|
||
|
|
|
||
|
|
Sphinx-friendly deployment options
|
||
|
|
----------------------------------
|
||
|
|
|
||
|
|
There are several possible options you have to host your Sphinx documentation.
|
||
|
|
Some of them are:
|
||
|
|
|
||
|
|
**Read the Docs**
|
||
|
|
`Read the Docs`_ is an online service specialized in hosting technical
|
||
|
|
documentation written in Sphinx, as well as MkDocs. They have a
|
||
|
|
number of extra features, such as versioned documentation, traffic and
|
||
|
|
search analytics, custom domains, user-defined redirects, and more.
|
||
|
|
|
||
|
|
**GitHub Pages**
|
||
|
|
`GitHub Pages`_ is a simple static web hosting tightly integrated with
|
||
|
|
`GitHub`_: static HTML is served from one of the branches of a project,
|
||
|
|
and usually sources are stored in another branch so that the output
|
||
|
|
can be updated every time the sources change (for example using `GitHub
|
||
|
|
Actions`_). It is free to use and supports custom domains.
|
||
|
|
|
||
|
|
**GitLab Pages**
|
||
|
|
`GitLab Pages`_ is a similar concept to GitHub Pages, integrated with
|
||
|
|
`GitLab`_ and usually automated with `GitLab CI`_ instead.
|
||
|
|
|
||
|
|
**Netlify**
|
||
|
|
`Netlify`_ is a sophisticated hosting for static sites enhanced by
|
||
|
|
client-side web technologies like JavaScript (so-called `"Jamstack"`_).
|
||
|
|
They offer support for headless content management systems and
|
||
|
|
serverless computing.
|
||
|
|
|
||
|
|
**Your own server**
|
||
|
|
You can always use your own web server to host Sphinx HTML documentation.
|
||
|
|
It is the option that gives more flexibility, but also more complexity.
|
||
|
|
|
||
|
|
All these options have zero cost, with the option of paying for extra features.
|
||
|
|
|
||
|
|
.. _Read the Docs: https://readthedocs.org/
|
||
|
|
.. _GitHub Pages: https://pages.github.com/
|
||
|
|
.. _GitHub: https://github.com/
|
||
|
|
.. _GitHub Actions: https://github.com/features/actions
|
||
|
|
.. _GitLab Pages: https://about.gitlab.com/stages-devops-lifecycle/pages/
|
||
|
|
.. _GitLab: https://gitlab.com/
|
||
|
|
.. _GitLab CI: https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/
|
||
|
|
.. _Netlify: https://www.netlify.com/
|
||
|
|
.. _"Jamstack": https://jamstack.org/
|