-
Notifications
You must be signed in to change notification settings - Fork 2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add descriptive section to deployment section of tutorial
- Loading branch information
1 parent
7d7c59a
commit d399a7a
Showing
2 changed files
with
58 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,57 @@ | ||
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. | ||
Among them: | ||
|
||
**Read the Docs** | ||
`Read the Docs`_ is an online service specialized in hosting technical | ||
documentation written in Sphinx, as well as MkDocs. They offer free web | ||
hosting for open source projects, sustained either by ethical advertising | ||
that is inserted into pages, or by a monthly subscription. 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. | ||
|
||
.. _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/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -35,4 +35,5 @@ project. | |
narrative-documentation | ||
describing-code | ||
automatic-doc-generation | ||
deploying | ||
end |