The JetBrain technology exchange group has been opened, and you can join the QQ search group number "786598704"

PyCharm Is a Python IDE with a set of tools that can help users improve their efficiency when developing with Python language. In addition, the IDE provides some advanced functions for professional Web development under the Django framework. This tutorial is a series of tutorials about creating a} Sphinx website.

Download PyCharm 2021.1

This series of tutorials is mainly about making a dependent project and virtual environment, and then making a simple Sphinx website.

Sphinx can be added to existing Python applications or libraries to provide documentation. But it can also be used as the project itself -- for example, a website. In the steps of this tutorial, we use Sphinx to launch a new website as a new Python project.

imagine

This tutorial will simulate the establishment of a website for a fictional company called "Schlockchain". The company clearly has a lot of marketing activities it wants to carry out. It also has some code and -- obviously -- patents it wants to show. Venture capitalists want a website. The founder is not a real technician, so they want to use Markdown.

New project

First, let's create a new directory and change it to:

$ mkdir schlockchain
$ cd schlockchain

Note: we use the Mac OS / Linux / WSL command shell syntax in this tutorial.

Python recommends that projects use virtual environments for isolation. Real Python has a good primer on virtual environments, including why, what, and how. Let's build a new virtual environment and store it in our project In the venv directory. Then we will "activate" it, which will change our command path to find it in the bin of the virtual environment first.

$ python3 -m venv .venv
$ source .venv/bin/activate

Pip is a package installer for Python. Update your pip Please note that in the following, due to the line above source, our shell is using the python 3 virtual environment Directory:

$ pip install --upgrade pip

Our new blank Python project is now ready to install Sphinx.

Installing Sphinx

Open this project directory in your favorite editor. We will create a requirements Txt file to install our package to store our dependency list. Now put the following line into this new file:

sphinx

We can now use the activated shellpip to install our dependencies:

$ pip install -r requirements.txt

Sphinx itself has many dependencies, so it may take some time to get all the packages. When we're done, let's make sure Sphinx is installed and on our path:

$ which sphinx-quickstart
[some path prefix].venv/bin/sphinx-quickstart

Sphinx has many commands (implemented in Python). They are added to your virtual environment bin directory. If you see Sphinx QuickStart, you're in good shape.

Create a Sphinx website

Sphinx has a website generator command called Sphinx QuickStart, which is now in the bin directory of your virtual environment.

Let's run it and answer some questions, accept most defaults (Note... Hide my directory path):

$ sphinx-quickstart 
Welcome to the Sphinx 3.2.1 quickstart utility.

Please enter values for the following settings (just press Enter to
accept a default value, if one is given in brackets).

Selected root path: .

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]: 

The project name will occur in several places in the built documentation.
> Project name: Schlockchain
> Author name(s): Paul Everitt <pauleveritt@me.com>
> Project release []: 

If the documents are to be written in a language other than English,
you can select a language here by its language code. Sphinx will then
translate text that it generates into that language.

For a list of supported codes, see
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-language.
> Project language [en]: 

Creating file /.../schlockchain/conf.py.
Creating file /.../schlockchain/index.rst.
Creating file /.../schlockchain/Makefile.
Creating file /.../schlockchain/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /.../schlockchain/index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Here is what our directory looks like after running:

(.venv) schlockchain pauleveritt$ ls
Makefile        _templates      make.bat
_build          conf.py         requirements.txt
_static         index.rst

About some of these catalog items:

• conf.py is the Sphinx configuration file

• index.rst is the "home page" or document at the top of our website

• Makefile (make.bat for Windows) is a simple command running program

• _ build (generated file)_ static (custom site assets) and_ There is an empty directory for templates.

Note: if you are using PyCharm  Wait for IDE, please_ The build directory is marked as ignored.

Well, that's today's content. The next section will continue to explain how to build a website.

The JetBrain technology exchange group has been opened. You can join by QQ search group number "786598704" or scanning the QR code below