Launching Sphinx (using github+Netlify)#

Last Updated on 2021-08-13

I summarized the procedure for building and managing your own site easily, by introducing Sphinx and collaborating with github/netlify.

About the environment#

Last Updated on 2021-08-14

Working environment at the time of writing this article.

OS#

Windows10 1909

Python#

3.9

cmd:

python

You can install it from the Microsoft Store.

edtor#

VSCODE 1.50.1

cmd:

code

You can install it from the Microsoft Store.

Preparing Python environment#

Last Updated on 2021-08-22

Preparing Python virtual environment#

Install Python in advance. This time, I separated it in a virtual environment to keep the Python environment clean. I used poetry.

Installation instructions

Hint

Note that pip install poetry is not a recommended procedure

Configure and Verify config for independent venv environment

poetry config --list
poetry config virtualenvs.in-project true

Creating pyproject.toml

poetry init

Create Virtual Environment

poetry install

.venv folder is created and you can add packages using ‘poetry add’ command.

I might touch Python code, so adding the following just in case

poetry add –dev flake8 autopep8 pylint

Sphinx#

Last Updated on 2021-08-22

Setting up Sphinx#

Adding Sphinx package:

poetry add --dev sphinx

Initialize Sphinx. Set folder target to ‘docs’:

portry run sphinx-quickstart docs

Now that ‘docs’ has been initialized, let’s try building it.

poetry run sphinx-build docs docs/_build/ja

You can confirm the build results by opening docs/_build/en/index.html [1]

Efficiency with sphinx-autobuild#

Using sphinx-autobuild can improve efficiency for building and browser checking.

Adding sphinx-autobuild:

poetry add --dev sphinx-autobuild

From now on, if you run the following command, you can check pages at http://127.0.0.1:8000 , and it will be built and reloaded automatically:

poerty run sphinx-autobuild docs docs/_build/ja

Efficiency for starting sphinx-autobuild#

Policy for improving startup efficiency#

Streamline execution commands by referring to the article 2019年に向けてPythonのモダンな開発環境について考える

poetry run doc //NG

該当記事のコマンドでの実現は失敗した。理由はpoetryで指定できる[tool.poetry.scripts]は引数指定ができないためである。 [2]

So take advantage of poethepoet as an alternative package:

poetry run poe doc

Apart from using the provisional package, this follows the same policy as Thinking about a modern Python development environment for 2019. Please refer to the URL for details.

Add poethepoet:

poetry add --dev poethepoet

Maintenance of setup.py#

Maintain setup.py.

setup.py#

  import os
  import subprocess
  from setuptools import setup, Command


  class SimpleCommand(Command):
      user_options = []

      def initialize_options(self):
          pass

      def finalize_options(self):
          pass


  class DocCommand(SimpleCommand):
      def run(self):
          subprocess.call(["sphinx-autobuild", "docs", "docs/_build/ja"])


  setup(
      cmdclass={
          "doc": DocCommand,
      },
  )

The following command can be used to execute the code of setup.py:

poetry run setup.py doc

Organizing pyproject.toml#

pyproject.toml#

[tool.poe.tasks]
  doc = "python setup.py doc"

This will result in sphinx-autobuild being launched with the following command:

poetry run poe doc

Theme#

The theme adopts pydata-sphinx-theme. The following is applicable in conf.py:

Links to Github and Twitter

Setting up the nav bar

Configure Google Analytics

Support for bootstrap4
Adopted by major packages such as Pandas, NumPy, etc.

Installing pydata-sphinx-theme:

poetry add --dev pydata-sphinx-theme

Organizing conf.py:

html_theme = "pydata_sphinx_theme"

For more details, see pydata-sphinx-theme

Integration with Github#

Last Updated on 2021-04-17

Create a repository and commit:

Preparing Github#

Get an account
Create Repository: Make it public for Netlify Integration
Reflect the source code: Refer to Github’s guide from git init to push

SSH communication to Github#

How to configure it so that it can be handled from the command line

Key generation#

Generation command:

ssh-keygen -t rsa

The following files will be generated: .ssh/id_rsa (private key) / .ssh/id_rsa.pub (public key)

Copy the public key to clipboard#

win:

clip < ~/.ssh/id_rsa.pub

mac:

pbcopy < ~/.ssh/id_rsa.pub

Register with Github#

Paste the contents of the clipboard from the “Add SSH Key” menu

githubの.ssh/config#

~/.ssh/config:

Host my.github.com
    HostName github.com
    User git
    Port  22
    Hostname  github
    IdentityFile  ~/.ssh/id_rsa
    TCPKeepAlive    yes
    IdentitiesOnly     yes

Github Connection Check#

Confirmation command:

ssh -T git@my.github.com

(Reference) In case of Gitlab:#

Netlify also supports Gitlab. Here is the SSH connection confirmation method for Gitlab:

Gitlab’s .ssh/config#

~/.ssh/config:

Host my.gitlab.com
    HostName   gitlab.com
    User  git
    Port    22
    IdentityFile   ~/.ssh/config/id_rsa
    TCPKeepAlive  yes
    IdentitiesOnly    yes

Gitlab Connection Check#

Confirmation command:

ssh -T git@my.gitlab.com

Netlify Integration#

Last Updated on 2021-04-17

Netlify allows integration with Github repositories, deploys to virtual machines on Netlify and makes it possible to publish the site.

Preparing for Netlify integration#

Build definition#

It is specified to read netlify.toml in the specified repository and build according to that.

netlify.toml#

[build]
  publish = "docs/_build/ja"
  command = "sphinx-build docs/ docs/_build/ja"

Publish refers to the folder to be published and command refers to the command used during build.

Python version#

The virtual environment that netlify starts up by default is Ubuntu 16.04 (as of November 2020). The default Python version is 2.7, so you need to change it. To specify the version, prepare a file called runtime.txt and use the version Enter the number.

runtime.txt#

13.7

Note that Python can be selected as versions 2.7, 3.5, and 3.7. Any other version specified will result in an error. [3]

Netlify Github integration#

You can log in to netlify with your github account. Log in and link to the build target repository. You can link from New Site from git.

Site confirmation#

The site is published with a random URL like https://jolly-brown-b98547.netlify.app/. Let’s check it.

Changing the URL to a custom domain#

It is possible to acquire a domain and change the URL.

Domain acquisition#

We will use freenom which can be obtained for free for trial purposes. [5]

Domain Settings#

It is set based on the official website’s procedure called “Configure an apex domain”. [4]

The DNS specified by netlify is set by the domain provider. On the netlifyDNS side, a special DNS record called Netlify record is set.

Another alternative is to directly specify the root as Netlify’s LB IP in the DNS of the domain provider as an A record, and set a CNAME record from ‘www’ to the apex subdomain.

Verify with own domain#

Access the configured URL to verify. If successful, access can be done with https. If it fails, error conditions are displayed on netlify’s management screen.