Sphinx: Wie man Dokumentation mit Sphinx generiert

Question

Wenn wir den Befehl sphinx-quickstart eingeben, müssen wir Werte für so viele Male eingeben.
Zum Beispiel:

> Root path for the documentation [.]: 
> Separate source and build directories (y/n) [n]: 
> Name prefix for templates and static dir [_]: 
> Project name: 
> Author name(s): 
> Project version []: 
> Project release []: 
> Project language [en]: 
> Source file suffix [.rst]: 
> Name of your master document (without suffix) [index]: 
> Do you want to use the epub builder (y/n) [n]: 
> autodoc: automatically insert docstrings from modules (y/n) [n]: 
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: 
> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: 
> todo: write "todo" entries that can be shown or hidden on build (y/n) [n]: 
> coverage: checks for documentation coverage (y/n) [n]: 
> imgmath: include math, rendered as PNG or SVG images (y/n) [n]: 
> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: 
> ifconfig: conditional inclusion of content based on config values (y/n) [n]: 
> viewcode: include links to the source code of documented Python objects (y/n) [n]: 
> githubpages: create .nojekyll file to publish the document on GitHub pages (y/n) [n]: 
> Create Makefile? (y/n) [y]: 
> Create Windows command file? (y/n) [y]: 

Gibt es eine Möglichkeit, um, dass wir auf diese lästige Arbeit nicht haben?
Zum Beispiel irgendein Bash-Skript oder Python-Skript?

Die entsprechenden Argumente sind:

> Project name: My Project 
> Author name(s): My Name 
> Project version []: 1 
> autodoc: automatically insert docstrings from modules (y/n) [n]: y 
> doctest: automatically test code snippets in doctest blocks (y/n) [n]: y 
> viewcode: include links to the source code of documented Python objects (y/n) [n]: y 

der Rest leer Alle sind nur Strings.

Meine Versuche

printf '\n\n\nMyProject\nBhishan Poudel\n1\n\n\n\n\n\ny\ny\n\n\n\n\n\n\ny\n\n\n\n' | sphinx-quickstart 

Versuch 2

# run_sphinx_quickstart.py 
#!/usr/bin/env python3 
import subprocess 

sphinx_args = { 
'Root_path'  : '', 
'Separate_source' : '', 
'Name_prefix'  : '', 
'Project_name'  : 'My Project', 
'Author_name'  : 'Bhishan Poudel', 
'Project_version' : '1', 
'Project_release' : '', 
'Project_language' : 'en', 
'Source_file'  : '.rst', 
'master_document' : 'index', 
'epub'    : '', 
'autodoc'   : 'y', 
'doctest'   : 'y', 
'intersphinx'  : 'n', 
'todo'    : 'n', 
'coverage'   : 'n', 
'imgmath'   : 'n', 
'mathjax'   : 'n', 
'ifconfig'   : 'n', 
'viewcode'   : 'y', 
'githubpages'  : 'n', 
'Makefile'   : 'y', 
'Windows_Makefile ': 'n' } 

for k,v in sphinx_args.items(): 
    print(k,'\t\t:', v) 


subprocess.call('sphink-quickstart', shell=True) 

# I don't know how to caputre the outputs of shell commands!! 

Hilfe wird wirklich geschätzt.

Weiterführende Links:

Answer 1

Sie sphinx-quickstart -q mit den Optionen aufrufen, die Sie mögen.

Answer 2

Der Link zur Dokumentation lautet Invocation of sphinx-quickstart.

Verwendung von Sphinx zum Erstellen von Dokumenten?

Benötigte Dateien:

• ~/.bash_profile
• ~/Anwendungen/edit_sphinx_conf.py
• ~/Anwendungen/custom.css
• ~/Anwendungen/Logos/Logo .jpg
• ~/.config/geany/snippets.conf
• ~/.config/geany/fildefends/filety pes.restructuredtext

Bash_profile

##============================================================================== 
# Sphinx documentation 
##============================================================================== 
alias sprm='rm -rf docs/build docs/html docs/Makefile docs/rst docs/source docs/pdf' 
alias spo='open docs/html/index.html' 



# Documentation using sphinx 
# Usage: spallf FOLDER 
# Final output: docs/html/index.html 
function spallf() { 

    #1. Create folders 
    mkdir -p docs/html docs/rst docs/rst/_static 

    #2. Copy custom.css file to rst/_static 
    cp ~/Applications/custom.css docs/rst/_static/ 

    #3. Quickstart 
    # Outputs: docs 
    # docs has three things: Makefile source build 
    sphinx-quickstart -q -p "Research" -a "Bhishan Poudel" -v 1 -r 0 \ 
    --ext-autodoc --ext-doctest --ext-viewcode --ext-imgmath \ 
    --no-batchfile --sep docs 

    #4. Copy edit_conf file 
    cp ~/Applications/edit_sphinx_conf.py edit_sphinx_conf.py 

    #5. Edit conf.py file. 
    python3 edit_sphinx_conf.py; rm -rf edit_sphinx_conf.py 

    #6. Create html folder (also creates doctrees). 
    cd docs; make html; cd -; pwd 


    #7. Auto create rst files. 
    sphinx-apidoc -o docs/rst "$1" 

    #8. Copy conf.py to docs/rst folder. 
    cp docs/source/conf.py docs/rst/; mv docs/rst/modules.rst docs/rst/index.rst 

    #9. Add path to conf.py 
    awk -v n=23 -v s="sys.path.append('../$1')" 'NR == n {print s} {print}' \ 
    docs/rst/conf.py > docs/rst/conf_new.py; 
    rm docs/rst/conf.py; mv docs/rst/conf_new.py docs/rst/conf.py 

    #10. Add Table of Contents to index.rst 
    awk -v n=1 -v s=".. contents:: Table of Contents\n :depth: 3\n\n" \ 
        'NR == n {print s} {print}' \ 
        docs/rst/index.rst > docs/rst/tmp; mv docs/rst/tmp docs/rst/index.rst 

    #11. Add Logo to index.rst 
    mkdir -p docs/html/_images 
    cp ~/Applications/logos/logo.jpg docs/html/_images/logo.jpg 
    awk -v n=1 -v s=" .. image:: ../html/_images/logo.jpg\n :height: 100px\n :width: 3000 px\n :align: center\n\n" \ 
        'NR == n {print s} {print}' \ 
        docs/rst/index.rst > docs/rst/tmp; mv docs/rst/tmp docs/rst/index.rst 


    #12. Build to get html and pdf 
    cd docs; sphinx-build -b html rst html; cd - 

    # Also generate pdf 
    #cd docs; sphinx-build -b latex rst latex; cd -; pwd 
    #cd docs/latex; make; cd - ; mkdir docs/pdf 
    #cp docs/latex/Research.pdf docs/pdf/Research.pdf; rm -r docs/latex 


    #12. Delete pycache 
    rm -rf "$1"/__pycache__ 

    #13. Open html 
    open docs/html/index.html 
    } 




# Add another folder to previous scripts. 
# Usage: spallf2 Another_folder 
function spallf2() { 
    sphinx-apidoc -o docs/rst "$1" 
    echo "" >> docs/rst/index.rst 
    echo "" >> docs/rst/index.rst 
    cat docs/rst/modules.rst >> docs/rst/index.rst 
    rm -rf docs/rst/modules.rst 
    awk -v n=25 -v s="sys.path.append('../$1')" 'NR == n {print s} {print}' docs/rst/conf.py > docs/rst/conf_new.py 
    cp docs/rst/conf_new.py docs/rst/tmp.py 
    rm -rf docs/rst/conf.py; mv docs/rst/conf_new.py docs/rst/conf.py 
    cd docs; make clean; cd - 
    cd docs; sphinx-build -b html rst html; cd - 
    rm -rf "$1"/__pycache__ 
    open docs/html/index.html 
    } 

edit_sphinx_conf.py

#!/usr/bin/env python3 
# -*- coding: utf-8 -*- 
# File  : ~/Applications/edit_sphinx_conf.py 
# Author  : Bhishan Poudel, Physics PhD Student, Ohio University 
# Date  : Jul 04, 2017 Tue 
# Ref: 
# http://www.sphinx-doc.org/en/stable/theming.html 
# 
# Imports 
import time 
import os 
import subprocess 

def edit_sphinx_conf_py(): 
    """Edit sphinx conf.py file.""" 

    html_theme_options = """html_theme_options = { 'linkcolor': '#808000', 
     'collapsiblesidebar': True, 
     'sidebarbgcolor': 'fuchia', 
     'sidebartextcolor': 'teal', 
     'sidebarlinkcolor': 'gray', 
     'relbarbgcolor': '#5D6D7E', 
     'externalrefs': True 
     } 
    """ 

    conf, conf2 = 'docs/source/conf.py', 'docs/source/conf2.py' 
    if os.path.isfile(conf): subprocess.call('mv %s %s '% (conf, conf2), shell=True) 
    with open(conf2, 'r') as f, open(conf,'w') as fo: 
     for line in f.readlines(): 
      olds = [r'# import os', 
        r'# import sys', 
        r"# sys.path.insert(0, os.path.abspath('.'))", 
        r"html_theme = 'alabaster'"] 
      news = [r'import os', 
        r'import sys', 
        r"sys.path.insert(0, os.path.abspath('.'))", 
        r"html_theme = 'classic'", 
        html_theme_options, 
        r"html_style = 'custom.css'"] 

      # os 
      if olds[0] in line: 
       print(line.replace(line, news[0]), file=fo, end='\n') 

      # sys 
      elif olds[1] in line: 
       print(line.replace(line, news[1]), file=fo, end='\n') 

      # path 
      elif olds[2] in line: 
       print(line.lstrip('#').lstrip(' '), file=fo, end='\n') 

      # theme 
      elif olds[3] in line: 
       print(line.replace(line, news[3]), file=fo) 
       print(news[4], file=fo) 
       print(news[5], file=fo) 

      # Other lines 
      else: 
       print(line, file=fo, end='') 
    os.remove(conf2) 
    print('Editing file: ', conf) 

if __name__ == '__main__': 
    edit_sphinx_conf_py() 

custom.css Datei: ~/Anwendungen/custom.css

@import url("classic.css"); 


div.admonition-todo { 
    border-top: 2px solid red; 
    border-bottom: 2px solid red; 
    border-left: 2px solid red; 
    border-right: 2px solid red; 
    background-color: #ff6347 
} 

div.admonition-info { 
    border-top: 2px solid green; 
    border-bottom: 2px solid green; 
    border-left: 2px solid green; 
    border-right: 2px solid green; 
    background-color: #63cc47 
} 

div.admonition-readme { 
    border-top: 2px solid red; 
    border-bottom: 2px solid red; 
    border-left: 2px solid red; 
    border-right: 2px solid red; 
    background-color: #F08080 
} 

Geany filetypes.restructuredtext Geany> Tools> Konfigurationsdateien> Dateityp Konfiguration> Markup Languages> Dateitypen.reStructuredText

Geany snippets.conf

##*********************************************************************** 
##======================================================================= 
##   reStructuredText (reST) 
##======================================================================= 
##*********************************************************************** 
[reStructuredText] 
# https://www.youtube.com/watch?v=L-fXOoxrt0M 
hdr=.. contents:: Table of Contents\n :depth: 3\n\n 
contents=.. contents:: Table of Contents\n :depth: 3\n\n 
toc=.. toctree::\n :maxdepth: 4\n\n %cursor% 
h=%cursor%\n################################################################################\n\n 
h2=%cursor%\n********************************************************************************\n\n 
h3=%cursor%\n================================================================================\n\n 
h4=%cursor%\n--------------------------------------------------------------------------------\n\n 
h5=%cursor%\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n 
h6=%cursor%\n""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""\n\n 
img=.. image:: ../images/%cursor%.png\n :height: 100px\n :width: 400 px\n :align: center\n 
fig=\n.. figure:: ../images/a.png\n :width: 200px\n :align: center\n :height: 100px\n :alt: alternate text\n :figclass: align-center\n\n This is caption.\n 
footnote=[#f1]_ \n\n.. rubric:: Footnotes\n\n.. [#f1] Text of the first footnote.\n\n 
cite=[book]_ \n\n.. [book] Name of book 
link=`Link text <%cursor%>`_ 
link2=`a link`_.\n\n.. _a link: %cursor%\n\n 
table=\n\n===== ===== =======\nA  B  A and B\n===== ===== =======\nF  F  F\nT  F  F\nF  T  F\nT  T  T\n===== ===== =======\n\n 
table2=\n\n+------------------------+------------+----------+----------+\n| Header1    | Header 2 | Header 3 | Header 4 |\n+========================+============+==========+==========+\n| ..      | 12   | 13  | 14  |\n+------------------------+------------+----------+----------+\n| 21      | 22   | 23  |  24 |\n+------------------------+------------+----------+----------+\n\n 
ss=|H2O|\n\n.. |H2O| replace:: H\ :sub:`2`\ O\n 
superscript=|H2O|\n\n.. |H2O| replace:: H\ :sub:`2`\ O\n 
code=::\n\n This is code. 
i=\n %cursor% 
# new line 
nl=\n| %cursor%\n| %cursor% 
doctest=>>> print 'this is a Doctest block'\nthis is a Doctest block 
hlist=.. hlist::\n :columns: 3\n\n * A list of\n * short items\n * that should be\n * displayed\n * horizontally\n\n 
note=.. note::\n\n %cursor%. 
seealso=.. seealso::\n\n %cursor%. 
seealso2=.. seealso::\n Module :py:mod:`zipfile`\n  Documentation of the :py:mod:`zipfile` standard module.\n\n `GNU tar manual, Basic Tar Format <http://link>`_\n  Documentation for tar archive files, including GNU tar extensions.\n 
warning=.. warning::\n\n Write complete sentence. 
todo=.. admonition:: todo\n\n %cursor% 
info=.. admonition:: Info\n\n %cursor% 
info=.. admonition:: Readme\n\n %cursor% 
code=.. code-block:: c\n\n printf("hi there");\n 
math=\n:math:`\alpha > \beta` 
math2=.. math::\n\n n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k\n 
topic=.. topic:: Topic\n\n Indented text is the body. 
sidebar=.. sidebar:: Sidebar\n\n Body. 
i=\n\n %cursor% 
test=.. testcode::\n\n print("hi")\n\n.. testoutput::\n\n hi\n 
class=:class:`~fibonacci_doctest` 
meth=:meth:`~fibonacci_doctest.fib` 
paired_index=.. index::\npair: poetry; bad # gives bad>poetry and poetry>bad. 
single_index=.. index::\nsingle: Pythagoras # gives bad>poetry and poetry>bad. 

Geany Befehle bauen

Open Geany text editor 
open index.rst 
Tools > Build > Set Build Commands > Execute > 
cd ../; make clean; sphinx-build -b html rst html && open html/index.html 
# For ubuntu use xdg-open instead of open 

Usage

pwd: Location of Scripts 
spallf Scripts 
Add another folder: spallf2 Scripts2 

Caveats
Sphinx kann nicht gut laufen in python2, für mich ist es funktionierte nur in anaconda3 Version. Sowohl der Standard python2 als auch python3 konnten den Befehl make html mit TemplatesNotFound error nicht ausführen.

Um mehrere Versionen von Python auszuführen, setzen Sie den Pfad von anaconda3 in den unteren von .bash_profile oder .bashrc dann sphinx wird gut laufen.

Übrigens braucht das Programm PHOSIM python2 und phosim put die python2 PATH Zeilen am unteren Rand von .bash_profile.

Das ist es! Es ist so schön und einfach, jetzt mit Sphinx zu dokumentieren.
Und natürlich sollte ich über rST lernen, die meinem Dokument besser aussehen wird.