sphinx-quickstart got messy and I tried to create an alternative command and the stress disappeared

Introduction

Documenting is very convenient for sphinx. However, sphinx-quickstart basically only needs a return, I was wondering if I could do something a little more. The more you use sphinx, the more you feel this hassle. I made something called sphinx-express.

Soliloquy: It's a brute force. It's a script that is neither cool nor beautiful. Well, it's like studying the click module, It works as expected.

Dependent module

I am using click and PyYAML. Also, sphinx expects version 1.7 or later.

$ python -m pip install click PyYAML 

How to use

The first time it is executed with the --setup option.

$ sphinx-express.py --setup

You should install follows packages.
python -m pip install sphinx-rtd-theme sphinx-charts pallets_sphinx_themes sphinxcontrib-runcmd sphinxcontrib-napoleon

your configfile: /Users/goichiiisaka/.sphinx/quickstartrc
your templatedir: /Users/goichiiisaka/.sphinx/templates/quickstart
quickstart templates of sphinx into your templatedir.

Now under $ HOME / .sphinx It will copy the template files that quickstartrc and sphinx have.

$ tree  ~/.sphinx/
/Users/goichiiisaka/.sphinx/
├── quickstartrc
└── templates
    └── quickstart
        ├── Makefile.new_t
        ├── Makefile_t
        ├── conf.py_t
        ├── make.bat.new_t
        ├── make.bat_t
        └── master_doc.rst_t

2 directories, 7 files

By default, ~ / .sphinx / quickstartrc does the following:


sep: true
language: ja
suffix: .rst
master: index
makefile: true
batchfile: true
autodoc: true
doctest: false
intersphinx: false
todo: false
coverage: false
imgmath: true
mathjax: true
ifconfig: true
viewcode: true
project: sample
version: 0.0.1
release: 0.0.1
lang: ja
make_mode: true
ext_mathjax: true
extensions:
- pallets_sphinx_themes
- sphinx_rtd_theme
- sphinx.ext.autodoc
- sphinx.ext.mathjax
- sphinx.ext.autosectionlabel
- sphinxcontrib.blockdiag
- sphinxcontrib.seqdiag
- sphinxcontrib.blockdiag
- sphinxcontrib.nwdiag
- sphinxcontrib.rackdiag
- sphinxcontrib.httpdomain
- sphinxcontrib.runcmd
- recommonmark
mastertocmaxdepth: 2
project_underline: ======

After that, if you modify this file, shpinx-express.py will load it for you A single command will set up the sphinx project directory.

$ sphinx-express.py sample
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: sample

Creating file /Users/goichiiisaka/docs/sample/source/conf.py.
Creating file /Users/goichiiisaka/docs/sample/source/index.rst.
Creating file /Users/goichiiisaka/docs/sample/Makefile.
Creating file /Users/goichiiisaka/docs/sample/make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file /Users/goichiiisaka/docs/sample/source/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.

I try to create a sphinx project directory if it doesn't exist. The project defaults to the project directory. author is the login username obtained by os.getlogin () by default.

$ python sphinx-express.py --help
()
Usage: sphinx-express.py [OPTIONS] [PROJECT_DIR]

  Create required files for a Sphinx project.

Options:
  -p, --project TEXT      project name. default is basename of PROJECT_DIR.
  -a, --author TEXT       author name. default is "goichiiisaka"
  -v, --ver TEXT          version of project. default is '0.0.1'
  -l, --lang TEXT         document language. default is 'ja'
  -t, --templatedir PATH  template directory for template files. default:
                          /Users/goichiiisaka/.sphinx/templates/quickstart

  -d, --define_value TEXT  define a template variable. NAME=VALUE
  -c, --configfile PATH   sphinx-express configfile. default:
                          /Users/goichiiisaka/.sphinx/quickstartrc

  -N, --new               Ignore least configures.
  --setup                 Copy quickstart templates and exit.
  --version               Show the version and exit.
  --help                  Show this message and exit.

template

~ / .sphinx / templates / quickstart / conf.py_t is In addition to copying, the following simple corrections are made.

# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#

# Avilable Themes: alabaster
{% set default_theme="alabaster" %}
{%- if 'sphinx_rtd_theme' in extensions -%}
# sphinx_rtd_theme
{% set default_theme="sphinx_rtd_theme" %}
{%- endif -%}
{%- if 'pallets_sphinx_themes' in extensions -%}
# babel, click, flask, jinja, platter, pocoo, werkzeug
{% set default_theme="flask" %}
{%- endif -%}
#
html_theme = "{{ default_theme }}"

{%- if 'sphinxcontrib.seqdiag' in extensions %}
# -- Options for seqdiag output -------------------------------------------

# curl -O https://ja.osdn.net/projects/ipafonts/downloads/51868/IPAfont00303.zip
import os
basedir = os.path.abspath(os.path.dirname(__file__))
seqdiag_fontpath = basedir + '/_fonts/IPAfont00303/ipagp.ttf'
seqdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.nwdiag' in extensions %}
# -- Options for nwdiag output --------------------------------------------

nwdiag_html_image_format = 'SVG'
rackiag_html_image_format = 'SVG'
packetdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.blockdiag' in extensions %}
# -- Options for blockdiag output ------------------------------------------

blockdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.actdiag' in extensions %}
# -- Options for actdiag output --------------------------------------------

actdiag_html_image_format = 'SVG'
{%- endif %}

{%- if 'sphinxcontrib.httpdomain' in extensions %}
# -- Options for httpdomain output ------------------------------------------

# List of HTTP header prefixes which should be ignored in strict mode:
http_headers_ignore_prefixes = ['X-']

# Strips the leading segments from the endpoint paths
# by given list of prefixes:
# http_index_ignore_prefixes = ['/internal', '/_proxy']

# Short name of the index which will appear on every page:
# http_index_shortname = 'api'

# Full index name which is used on index page:
# http_index_localname = "My Project HTTP API"

# When True (default) emits build errors when status codes,
# methods and headers are looks non-standard:
http_strict_mode = True
{%- endif %}


{%- if 'recommonmark' in extensions %}
# -- Options for recommonmark output ----------------------------------------
import recommonmark
from recommonmark.transform import AutoStructify

# At the bottom of conf.py
def setup(app):
    app.add_config_value('recommonmark_config', {
            'url_resolver': lambda url: github_doc_root + url,
            'auto_toc_tree_section': 'Contents',
            }, True)
    app.add_transform(AutoStructify)
{%- endif %}


Tips

I may not use it much, If you define variables in ~ /, sphinx / quickstartrc, You can set the value to the variable of jinja2 used in the template file.

variables:
- NAME=VALUE

TODO I want to make a package. No, I should do it ...

Recommended Posts

sphinx-quickstart got messy and I tried to create an alternative command and the stress disappeared
I tried to summarize the umask command
I tried to control the network bandwidth and delay with the tc command
How to create an article from the command line
I tried to illustrate the time and time in C language
I tried to display the time and today's weather w
I tried to enumerate the differences between java and python
I tried to create an article in Wiki.js with SQLAlchemy
I got an error when I tried to process luigi in parallel on windows, but the solution
I tried to create an environment of MkDocs on Amazon Linux
[Linux] I tried to summarize the command of resource confirmation system
I tried to create serverless batch processing for the first time with DynamoDB and Step Functions
I tried to create Bulls and Cows with a shell program
I want to connect remotely to another computer, and the nautilus command
I tried to move the ball
I tried to estimate the interval.
I made a POST script to create an issue on Github and register it in the Project
[Python] I tried to summarize the set type (set) in an easy-to-understand manner.
I tried moving the image to the specified folder by right-clicking and left-clicking
I tried to visualize the age group and rate distribution of Atcoder
I tried to express sadness and joy with the stable marriage problem.
I got an error when trying to install Xgboost and its solution
I tried to extract and illustrate the stage of the story using COTOHA
I tried to verify and analyze the acceleration of Python by Cython
I want to leave an arbitrary command in the command history of Shell
I tried to create a sample to access Salesforce using Python and Bottle
I implemented the VGG16 model in Keras and tried to identify CIFAR10
I tried to create a linebot (implementation)
I tried to create a linebot (preparation)
I tried to recognize the wake word
I tried to summarize the graphical modeling.
I tried to estimate the pi stochastically
I tried to touch the COTOHA API
I tried to notify the update of "Hamelin" using "Beautiful Soup" and "IFTTT"
Zip-compress any file with the [shell] command to create a file and delete the original file.
I made an appdo command to execute a command in the context of the app
I made an image classification model and tried to move it on mobile
I tried to process and transform the image and expand the data for machine learning
[LIVE] I tried to deliver the sunrise and sunset times nationwide every day
[Introduction to AWS] I tried porting the conversation app and playing with text2speech @ AWS ♪
I tried to create an environment to check regularly using Selenium with AWS Fargate
I tried to pass the G test and E qualification by training from 50
I tried to create a model with the sample of Amazon SageMaker Autopilot
I tried web scraping to analyze the lyrics.
I implemented DCGAN and tried to generate apples
I tried to optimize while drying the laundry
I tried to get an image by scraping
I tried to save the data with discord
I tried to touch the API of ebay
I tried to correct the keystone of the image
I tried to detect an object with M2Det!
Qiita Job I tried to analyze the job offer
LeetCode I tried to summarize the simple ones
Create a command to get the work log
[Introduction to PID] I tried to control and play ♬
I tried to implement the traveling salesman problem
I tried to predict the price of ETF
I tried to vectorize the lyrics of Hinatazaka46!
[LPIC 101] I tried to summarize the command options that are easy to make a mistake
I tried to notify the update of "Become a novelist" using "IFTTT" and "Become a novelist API"
I tried to understand how to use Pandas and multicollinearity based on the Affairs dataset.