Sphinx format for Latex and HTML

Transcription

1 Sphinx format for Latex and HTML Meher Krishna Patel Created on : Octorber, 2017 Last updated : May, 2018 More documents are freely available at PythonDSP

2 Table of contents Table of contents List of figures List of tables i ii iii 1 conf.py settings for Latex 1 2 Basic Patterns Toctree Quotes Above the chapter name in Latex HTML and Latex Only HTML Admonitions Figures and listing Figures Figure scaling and alignment Listings Number list Bullets Mixed i

3 List of figures 3.1 Mastery in Servitude (center aligned) Mastery in Servitude (without align option) ii

4 List of tables iii

5 Chapter 1 conf.py settings for Latex Replace the contents of conf.py with following contents, Change the name of the document i.e. replace Sphinx format for Latex and HTML with correct name. Change the date in Created on : October, Change main.tex with desired file name. If require, uncomment \listoffigures and \listoftables for table of contents. Change margin in sphinxsetup, in required. Copy all files of _static and _template folder to current project. These can be downloaded from this repository. Change report to book in latex_documents for double-sided printing format. The complete template is loaded for further clarification.!/usr/bin/env python3 -*- coding: utf-8 -*- 'Sphinx format for Latex and HTML' documentation build configuration file, created by sphinx-quickstart on Thu Oct 5 21:04: This file is execfile()d with the current directory set to its containing dir. Note that not all possible configuration values are present in this autogenerated file. All configuration values have a default; values that are commented out serve to show the default. If extensions (or modules to document with autodoc) are in another directory, add these directories to sys.path here. If the directory is relative to the documentation root, use os.path.abspath to make it absolute, like shown here. import os import sys sys.path.insert(0, os.path.abspath('.')) -- General configuration If your documentation needs a minimal Sphinx version, state it here. needs_sphinx = '1.0' Add any Sphinx extension module names here, as strings. They can be extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. (continues on next page) 1

6 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.mathjax', 'sphinx.ext.ifconfig', 'sphinx.ext.viewcode', 'sphinx.ext.githubpages'] (continued from previous page) Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] The suffix(es) of source filenames. You can specify multiple suffix as a list of string: source_suffix = ['.rst', '.md'] source_suffix = '.rst' The master toctree document. master_doc = 'index' General information about the project. project = 'Sphinx format for Latex and HTML' copyright = '2017, Meher Krishna Patel' author = 'Meher Krishna Patel' The version info for the project you're documenting, acts as replacement for version and release, also used in various other places throughout the built documents. The short X.Y version. version = '1.0' The full version, including alpha/beta/rc tags. release = '0' The language for content autogenerated by Sphinx. Refer to documentation for a list of supported languages. This is also used if you do content translation via gettext catalogs. Usually you set "language" from the command line for these cases. language = None List of patterns, relative to source directory, that match files and directories to ignore when looking for source files. This patterns also effect to html_static_path and html_extra_path exclude_patterns = [] The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' If true, `todo` and `todolist` produce output, else they produce nothing. todo_include_todos = True -- Options for HTML output The theme to use for HTML and HTML Help pages. See the documentation for a list of builtin themes. html_theme = 'nature' (continues on next page) 2 PythonDSP

7 Chapter 1. conf.py settings for Latex html_theme = 'alabaster' html_theme = 'sphinx_rtd_theme' (continued from previous page) Theme options are theme-specific and customize the look and feel of a theme further. For a list of options available for each theme, see the documentation. html_theme_options = {} Add any paths that contain custom static files (such as style sheets) here, relative to this directory. They are copied after the builtin static files, so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] Custom sidebar templates, must be a dictionary that maps document names to template names. This is required for the alabaster theme refs: html_sidebars = { '**': [ 'about.html', 'navigation.html', 'relations.html', needs 'show_related': True theme option to display 'searchbox.html', 'donate.html', ] } -- Options for HTMLHelp output Output file base name for HTML help builder. htmlhelp_basename = 'maindoc' -- Options for LaTeX output latex_engine = 'pdflatex' latex_elements = { The paper size ('letterpaper' or 'a4paper'). 'papersize': 'a4paper', 'releasename':" ", Sonny, Lenny, Glenn, Conny, Rejne, Bjarne and Bjornstrup 'fncychap': '\\usepackage[lenny]{fncychap}', 'fncychap': '\\usepackage{fncychap}', 'fontpkg': '\\usepackage{amsmath,amsfonts,amssymb,amsthm}', 'figure_align':'htbp', The font size ('10pt', '11pt' or '12pt'). 'pointsize': '10pt', Additional stuff for the LaTeX preamble. 'preamble': r''' %% %% %% %% %% %% %% %% %% %% Meher %% %% %% %% %% %% %% %% %% %% %add number to subsubsection 2=subsection, 3=subsubsection %% % below subsubsection is not good idea. (continues on next page) 3 Meher Krishna Patel

8 \setcounter{secnumdepth}{3} % %% %% Table of content upto 2=subsection, 3=subsubsection \setcounter{tocdepth}{2} (continued from previous page) \usepackage{amsmath,amsfonts,amssymb,amsthm} \usepackage{graphicx} %% % r educe spaces for Table of contents, figures and tables %% % i t is used "\addtocontents{toc}{\vskip -1.2cm}" etc. in the document \usepackage[notlot,nottoc,notlof]{} \usepackage{color} \usepackage{transparent} \usepackage{eso-pic} \usepackage{lipsum} \usepackage{footnotebackref} %% link at the footnote to go to the place of footnote in the text %% spacing between line \usepackage{setspace} %% %% \onehalfspacing %% %% \doublespacing \singlespacing %% %% %% %% %% % d atetime \usepackage{datetime} \newdateformat{monthyearformat}{% \monthname[\themonth], \THEYEAR} %% RO, LE will not work for 'oneside' layout. %% Change oneside to twoside in document class \usepackage{fancyhdr} \pagestyle{fancy} \fancyhf{} %% % Alternating Header for oneside \fancyhead[l]{\ifthenelse{\isodd{\value{page}}}{ \small \nouppercase{\leftmark} }{}} \fancyhead[r]{\ifthenelse{\isodd{\value{page}}}{}{ \small \nouppercase{\rightmark} }} %% % Alternating Header for two side %\fancyhead[ro]{\small \nouppercase{\rightmark}} %\fancyhead[le]{\small \nouppercase{\leftmark}} %% for oneside: change footer at right side. If you want to use Left and right then use same as header defined above. \fancyfoot[r]{\ifthenelse{\isodd{\value{page}}}{{\tiny Meher Krishna Patel} }{\href{ pythondsp.readthedocs.io/en/latest/pythondsp/toc.html}{\tiny PythonDSP}}} %% % Alternating Footer for two side %\fancyfoot[ro, RE]{\scriptsize Meher Krishna Patel (mekrip@gmail.com)} %% % page number \fancyfoot[co, CE]{\thepage} \renewcommand{\headrulewidth}{0.5pt} \renewcommand{\footrulewidth}{0.5pt} (continues on next page) 4 PythonDSP

9 Chapter 1. conf.py settings for Latex \RequirePackage{tocbibind} %% % c omment this to remove page number for following \addto\captionsenglish{\renewcommand{\contentsname}{table of contents}} \addto\captionsenglish{\renewcommand{\listfigurename}{list of figures}} \addto\captionsenglish{\renewcommand{\listtablename}{list of tables}} % \addto\captionsenglish{\renewcommand{\chaptername}{chapter}} (continued from previous page) %% reduce spacing for itemize \usepackage{enumitem} \setlist{nosep} %% %% %% %% %% % Quote Styles at the top of chapter \usepackage{epigraph} \setlength{\epigraphwidth}{0.8\columnwidth} \newcommand{\chapterquote}[2]{\epigraphhead[60]{\epigraph{\textit{1}}{\textbf {\textit{--2}}}}} %% %% %% %% %% % Quote for all places except Chapter \newcommand{\sectionquote}[2]{{\quote{\textit{``1''}}{\textbf {\textit{--2}}}}} ''', 'maketitle': r''' \pagenumbering{roman} %% % to avoid page 1 conflict with actual page 1 \begin{titlepage} \centering \vspace*{40mm} %% % * is used to give space from top \textbf{\huge {Sphinx format for Latex and HTML}} \vspace{0mm} \begin{figure}[!h] \centering \includegraphics[scale=0.3]{logo.jpg} \end{figure} \vspace{0mm} \Large \textbf{{meher Krishna Patel}} \small Created on : Octorber, 2017 \vspace*{0mm} \small Last updated : \MonthYearFormat\today %% \vfill adds at the bottom \vfill \small \textit{more documents are freely available at }{\href{ io/en/latest/pythondsp/toc.html}{pythondsp}} \end{titlepage} \clearpage \pagenumbering{roman} \tableofcontents \listoffigures \listoftables \clearpage \pagenumbering{arabic} ''', Latex figure (float) alignment (continues on next page) 5 Meher Krishna Patel

10 'figure_align': 'htbp', 'sphinxsetup': \ 'hmargin={0.7in,0.7in}, vmargin={1in,1in}, \ verbatimwithframe=true, \ TitleColor={rgb}{0,0,0}, \ HeaderFamily=\\rmfamily\\bfseries, \ InnerLinkColor={rgb}{0,0,1}, \ OuterLinkColor={rgb}{0,0,1}', (continued from previous page) 'tableofcontents':' ', } latex_logo = '_static/logo.jpg' Grouping the document tree into LaTeX files. List of tuples (source start file, target name, title, author, documentclass [howto, manual, or own class]). latex_documents = [ (master_doc, 'main.tex', 'Sphinx format for Latex and HTML', 'Meher Krishna Patel', 'report') ] -- Options for Epub output Bibliographic Dublin Core info. epub_title = project epub_author = author epub_publisher = author epub_copyright = copyright The unique identifier of the text. This can be a ISBN number or the project homepage. epub_identifier = '' A unique identification for the text. epub_uid = '' A list of files that should not be packed into the epub file. epub_exclude_files = ['search.html'] Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = {' None} def setup(app): app.add_stylesheet('custom.css') remove line numbers app.add_javascript('copybutton.js') show/hide prompt >>> use :numref: for references (instead of :ref:) numfig = True smart_quotes = False html_use_smartypants = False html_theme = 'sphinx_rtd_theme' 6 PythonDSP

11 Who says God has created this world? We have created it by our own imagination.god is supreme, independent. When we say he has created this illusion, we lower him and his infinity. He is beyond all this.only when we find him in ourselves, and even in our day to day life, do all doubts vanish. Chapter 2 Meher Baba Basic Patterns 2.1 Toctree Following code is added to index.rst. Look for the includehidden here. It will show all the hidden contents in the TOC. See next point for clarification... toctree:: :maxdepth: 3 :numbered: :includehidden: :caption: Contents: sphinx_basics/readme sphinx_basics/basics num-fig/numfig_index Above toctree contins fig-num/numfig_index ; and the fig-num/numfig_index.rst file contains following contents in it... toctree:: :maxdepth: 3 :hidden: :caption: Contents: fig list Note that hidden is used in numfig_index.rst. Therefore, it will not be dislayed in the html page of num-fig/numfig_index. But, includehidden is used in the index.rst, therefore the toctree of numfig_index.rst will be added in the top level table of contents. Also, Latex will include only top level table of contents in all cases. 2.2 Quotes Above the chapter name in Latex Use below code and the quote will appear in Latex file only. Code 7

12 2.3. Admonitions.. raw:: latex \chapterquote{who says God has created this world? We have created it by our own imagination.god is supreme, independent. When we say he has created this illusion, we lower him and his infinity. He is beyond all this.only when we find him in ourselves, and even in our day to day life, do all doubts vanish.}{meher Baba} HTML and Latex Use epigraph for quotes in HTML and Latex files as below, Code.. epigraph:: Result Who says God has created this world? We have created it by our own imagination.god is supreme, independent. When we say he has created this illusion, we lower him and his infinity. He is beyond all this. Only when we find him in ourselves, and even in our day to day life, do all doubts vanish. -- Meher Baba Who says God has created this world? We have created it by our own imagination.god is supreme, independent. When we say he has created this illusion, we lower him and his infinity. He is beyond all this. Only when we find him in ourselves, and even in our day to day life, do all doubts vanish. Meher Baba Only HTML Below quote will appear in HTML only, Code.. only:: html Result.. epigraph:: Who says God has created this world? We have created it by our own imagination.god is supreme, independent. When we say he has created this illusion, we lower him and his infinity. He is beyond all this. Only when we find him in ourselves, and even in our day to day life, do all doubts vanish. -- Meher Baba 2.3 Admonitions Admonitions can be used for custom headings for notes and warnigs etc. Following are the possible classeds for it, attention, caution danger 8 PythonDSP

13 Chapter 2. Basic Patterns error hint important note tip warning.. admonition:: Codes and Datasets :class: danger Below is x = 2,.. code-block:: c int x = 2; Codes and Datasets Below is x = 2, int x = 2; 9 Meher Krishna Patel

14 Chapter 3 Figures and listing Following toctree is used in this page. Look for the hidden here. See details in Section toctree:: :maxdepth: 3 :hidden: :caption: Contents: fig list 3.1 Figures Figure scaling and alignment In HTML behavior of alignment dependents on the browser. Same happens in the LatexPDF. Use center aligned or without delaring align as it works well in both HTML and Latex. Subfigures are not supported by Sphinx, but can be done using third part packages. Code.. figure:: figures/logo.jpg :scale: 20% :align: center Mastery in Servitude (center aligned).. figure:: figures/logo.jpg :scale: 20% Result Mastery in Servitude (without align option) 3.2 Listings Number list Code 10

15 Chapter 3. Figures and listing Fig. 3.1: Mastery in Servitude (center aligned) Fig. 3.2: Mastery in Servitude (without align option). Data 1. Data 2. Data 3 Result a. sub data 1 b. sub data 2 ) sub data 1 ) sub data 2 ) sub data 3 1. Data 1 2. Data 2 (a) sub data 1 (b) sub data 2 3. Data 3 (a) sub data 1 (b) sub data 2 (c) sub data Bullets Code 11 Meher Krishna Patel

16 3.2. Listings * Data 1 * Data 2 * Data 3 Result - sub data 1 - sub data 2 - sub data 3 Data 1 Data 2 Data 3 sub data 1 sub data 2 sub data Mixed Code. Data 1 a. sub data 1 b. sub data 2. Data 2 Result * sub data 1 * sub data 2 1. Data 1 (a) sub data 1 (b) sub data 2 2. Data 2 sub data 1 sub data 2 12 PythonDSP