Sphinx Site Generator
Felicity
Sphinx is a documentation generator or a tool that translates a set of plaintext source files into various output formats, automatically producingcross-references, indices, etc. That is, if you have a directory containing abunch of reStructuredText or Markdowndocuments, Sphinx can generate a series of HTML files, a PDF file (via LaTeX),man pages and much more.
The root directory of a Sphinx collection of plain-text document sources iscalled the source directory. This directory also contains the Sphinxconfiguration file conf.py, where you can configure all aspects of howSphinx reads your sources and builds your documentation. [1]
Sphinx comes with a script called sphinx-quickstart that sets up asource directory and creates a default conf.py with the most usefulconfiguration values from a few questions it asks you. To use this, run:
This is exactly how the toctree for this documentation looks. Thedocuments to include are given as document names, which in shortmeans that you leave off the file name extension and use forward slashes(/) as directory separators.
You can now create the files you listed in the toctree and add content, andtheir section titles will be inserted (up to the maxdepth level) at theplace where the toctree directive is placed. Also, Sphinx now knows aboutthe order and hierarchy of your documents. (They may contain toctreedirectives themselves, which means you can create deeply nested hierarchies ifnecessary.)
In Sphinx source files, you can use most features of standardreStructuredText. There are also several features added by Sphinx.For example, you can add cross-file references in a portable way (which worksfor all output types) using the ref role.
However, sphinx-quickstart script creates a Makefile and amake.bat which make life even easier for you. These can be executed byrunning make with the name of the builder. For example.
There are several more directives for documenting other types of Pythonobjects, for example py:class or py:method. There isalso a cross-referencing role for each of these object types. Thismarkup will create a link to the documentation of enumerate().
Earlier we mentioned that the conf.py file controls how Sphinxprocesses your documents. In that file, which is executed as a Python sourcefile, you assign configuration values. For advanced users: since it isexecuted by Sphinx, you can do non-trivial tasks in it, like extendingsys.path or importing a module to find out the version you aredocumenting.
The config values that you probably want to change are already put into theconf.py by sphinx-quickstart and initially commented out(with standard Python syntax: a # comments the rest of the line). Tochange the default value, remove the hash sign and modify the value. Tocustomize a config value that is not automatically added bysphinx-quickstart, just add an additional assignment.
When documenting Python code, it is common to put a lot of documentation in thesource files, in documentation strings. Sphinx supports the inclusion ofdocstrings from your modules with an extension (an extension is a Pythonmodule that provides additional features for Sphinx projects) called autodoc.
Installing sphinx is as easy as pip install sphinx (on Linux andWindows). pip will download a bunch of other dependencies (docutils,Jinja2, pygments as well). Once installed, check whether sphinx isavailable to you by typing $ sphinx-quickstart at the commandline. This should give you a welcome message. We proceed from there inthe next section. (On Windows, if you have addedC:\Python27\Scripts to the Windows Path variable, the sphinxcommands should be already available to be executed since thesphinx binaries are also installed in this location).
Go to your directory (say demo) where you want to create the content of yourstatic site and execute the sphinx-quickstart command. It shoulddisplay a welcome message and start a wizard asking you variousquestions about your new site.
The executable now creates a directory structure, and you will see thedirectories _build, _static, _templates and the files conf.py,index.rst, make.bat, Makefile created in the current directory foryou.
We will soon understand in detail what each of these are and how wecan start creating content for the site. Before that, type makehtml in the directory where you created the directorystructure. This command builds the HTML for your site, and placesthose files in the directory html under _build. You will noticethat there is a index.html file in that directory. This is yourhomepage or the master page of your site. Open this file in yourbrowser. You should see a web page similar to this one:
Now, rebuild the HTML pages using make html. If you reopen (orrefresh) the index.html page, you will see that it has links tothe contents of page1.rst. The .. toctreedirective does all the magic of creating the table of contents onthis page, and you can control the depth of the table of contentsusing the number after :maxdepth.
conf.py in your static site root directory is a Python file whichcontains all the configuration details used by sphinx when you triggera build process. There are a number of configuration statements forLaTex, Unix man page and Windows help file output, which you canremove, since we only plan to generate HTML output. That will leavethe default and HTML specific configuration options. As you willnotice, this file has been created from your responses to thesphinx-quickstart command. The conf.py file after tweaking andcustomizing looks like this (along with the associatedcomments; created using pycco).
Using this extension renders math using Mathjax. To include mathequations in your pages, use the ::math directive. For example::math:`ax^2+bx+c`, will render the equation as you can see in theHTML of page1.html. The input language is LaTex. Equation blocksmay be written, like so:
The youtubeextension allows embedding YouTube videos in your HTML pages. Toinstall it, go to the youtube directory of the sphinx-contribclone/download and install the extension using python setup.pyinstall.
If you are going to store your sphinx root directory in a publicsource code repository, you can use read the docs. I highly recommend using this option if you aregoing to store your documentation sources in a public repository. Onceyou have setup the appropriate hook, your sources would be builtautomatically everytime you push a change.
Create an empty file with the name .nojekyll. This is to allow usto use file and directory names beginning with _, as it tellsJekyll not to process it. (See herefor the background). You will recall that we have directories such as_static and _templates generated by Sphinx in htmldirectory, and hence we will need to create this file.
Everybody knows Sphinx for documenting projects, Python and otherwise.But few think of Sphinx for the rest of a website.Why?Because Sphinx traditionally means authoring with reStructuredText (RST) instead of Markdown.While RST is very powerful, it's a bit quirky, and nowhere near the popularity of Markdown.
But with the arrival of full Markdown support via MyST, and with static site generators having a renaissance, it's time to give Sphinx a second look.Sphinx is an "information-rich" static site generator, with rich linking and many other features for authoring.
But with the arrival of full Markdown support MyST, and with static site generators having a renaissance, it's time to give Sphinx a second look. Sphinx is an "information-rich" static site generator, with rich linking and many other features for authoring a knowledge base.
Each course comes with subtitles and full transcripts.The transcripts are available as a separate searchable page foreach lecture. They also are available in course-wide search resultsto help you find just the right lecture.
Hi there! I'm Paul Everitt, Python and Web developer advocate at JetBrains. I've been involved with Python since 1993.
You can find me speaking at Python conferences, hosting webcasts on JetBrains' YouTube chanel, blogging, and supporting the developer community.
This course is based upon Python 3. Python 2 is officially unsupported as of January 1st, 2020 andwe believe that it would be ill-advised to teach or learn Python 2. This course is, and has always been, built around Python 3.
This course is delivered in 1440p (4x the pixels as 720p). When you're watching the videos for this course, it will feel like you're sitting next to the instructor looking at their screen.
Learning GitHub or any source control system backed by git for documentation sites takes some time and practice. This set of lessons uses the Terminal rather than the desktop application or the web site UI, though both are valid ways to do a Git workflow.
Sphinx works with either major versions of Python active today, Python 2 and Python 3. Python 3 is the current and recommended version, and Python 2 is an unsupported Python version. Sphinx is a documentation tool that creates HTML, CSS, and JavaScript files from ReStructured text files.
Jekyll is a Static Site Generator that typically accepts Markdown for authoring. Jekyll has its own documentation site and a Quickstart. To prepare your environment to build Jekyll sites locally, follow the instructions for either Windows or MacOS.
To build Hugo sites locally, install Homebrew and Hugo. You do not need to install Go to use Hugo as your static site generator. These instructions are for a Mac or Linux system, but you can also read the Windows installation instructions on the gohugo.io site.
Continuous deployment lets you build the docs on another system and then place the files where the web server can serve them. CD can include both the building of the HTML files as well as deploying them to a host.
Themes for static site generators often provide advanced user experience features such as navigation, search, and responsive designs for mobile consumption. You also analyze the theme to make decisions on the authoring side, such as a table format for large data tables.
4a15465005