From fe504d755338314926c97f4997989be204126b94 Mon Sep 17 00:00:00 2001 From: Christopher Denter Date: Wed, 16 Mar 2011 13:48:07 +0100 Subject: [PATCH] Docs: First take at nicer PDF generation. Basic fonts/layout adapted by Flask (thanks Armin). Adapted our website color scheme where applicable. Also added a Pygments highlighting style for code snippets. To generate: make pdf in root folder and the pdf will be in doc/build/latex/Kivy.pdf TODO: * Get proper logo file for frontpage * Write Pygments lexer for kv lang * Would be nice if code boxes were also rounded. Find LaTeX guru --- Makefile | 5 + doc/sources/conf.py | 16 +- doc/sources/kivystyle.sty | 161 +++++++++++++++++++ doc/sources/logo.pdf | Bin 0 -> 4359 bytes doc/sources/sphinxext/kivy_pygments_theme.py | 87 ++++++++++ kivy/tools/pep8checker/pep8kivy.py | 2 +- 6 files changed, 266 insertions(+), 5 deletions(-) create mode 100644 doc/sources/kivystyle.sty create mode 100644 doc/sources/logo.pdf create mode 100644 doc/sources/sphinxext/kivy_pygments_theme.py diff --git a/Makefile b/Makefile index 0c365df7c..349ee843e 100644 --- a/Makefile +++ b/Makefile @@ -8,6 +8,9 @@ mesabuild: build: $(PYTHON) setup.py build_ext --inplace +pdf: + $(MAKE) -C doc latex && make -C doc/build/latex all-pdf + style: $(PYTHON) $(CHECKSCRIPT) $(KIVY_DIR) @@ -15,6 +18,8 @@ stylereport: $(PYTHON) $(CHECKSCRIPT) -html $(KIVY_DIR) hook: + # Install pre-commit git hook to check your changes for styleguide + # consistency. cp kivy/tools/pep8checker/pre-commit.githook .git/hooks/pre-commit chmod +x .git/hooks/pre-commit diff --git a/doc/sources/conf.py b/doc/sources/conf.py index fa2addef7..5fadfa121 100644 --- a/doc/sources/conf.py +++ b/doc/sources/conf.py @@ -44,7 +44,7 @@ master_doc = 'index' # General substitutions. project = 'Kivy' -copyright = '2010, kivy-dev' +copyright = '2010, The Kivy Authors' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. @@ -84,7 +84,7 @@ today_fmt = '%B %d, %Y' #show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'kivy_pygments_theme.KivyStyle' # Options for HTML output @@ -168,16 +168,24 @@ htmlhelp_basename = 'Kivydoc' # (source start file, target name, title, author, document class [howto/manual]). latex_documents = [ ('index', 'Kivy.tex', 'Kivy Documentation', - 'kivy-dev', 'manual'), + 'The Kivy Developers', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of # the title page. #latex_logo = None +latex_elements = { + 'fontpkg': r'\usepackage{mathpazo}', + 'papersize': 'a4paper', + 'pointsize': '8pt', + 'preamble': r'\usepackage{kivystyle}' +} +latex_additional_files = ['kivystyle.sty', 'logo.pdf'] + # For "manual" documents, if this is true, then toplevel headings are parts, # not chapters. -#latex_use_parts = False +latex_use_parts = True # Additional stuff for the LaTeX preamble. #latex_preamble = '' diff --git a/doc/sources/kivystyle.sty b/doc/sources/kivystyle.sty new file mode 100644 index 000000000..9e653fa2d --- /dev/null +++ b/doc/sources/kivystyle.sty @@ -0,0 +1,161 @@ +\definecolor{TitleColor}{rgb}{0,0,0} +\definecolor{InnerLinkColor}{rgb}{0,0,0} +% Make links the same color as links on the website +\definecolor{OuterLinkColor}{rgb}{0.875,0.392,0.133} + +% TODO Find a way not to have this active when printing the file +\definecolor{bgcolor}{rgb}{0.98,0.98,0.945} +\pagecolor{bgcolor} + +% Color for warning boxes +\definecolor{warningcolor}{rgb}{0.78,0.18,0} + +% This could be used to add a tiled background: +%\usepackage{wallpaper} +%\ThisTileSquareWallPaper{10}{background.png} + +% Code background color +\definecolor{VerbatimColor}{rgb}{0.925,0.918,0.882} + +% Palatino needs more leading (space between lines) +\linespread{1.05} + + +% Override default commands below for custom style: + +\renewcommand{\maketitle}{% + \begin{titlepage}%1 + \let\footnotesize\small + \let\footnoterule\relax + \ifsphinxpdfoutput + \begingroup + % This \def is required to deal with multi-line authors; it + % changes \\ to ', ' (comma-space), making it pass muster for + % generating document info in the PDF file. + \def\\{, } + \pdfinfo{ + /Author (\@author) + /Title (\@title) + } + \endgroup + \fi + \begin{flushright}% + %\sphinxlogo% + {\center + \vspace*{3cm} + \includegraphics[scale=0.7]{logo.pdf} + \vspace{3cm} + \par + {\rm\Huge \@title \par}% + {\em\LARGE \py@release\releaseinfo \par} + % Small hack to get the URL onto the first page + {\small www.kivy.org} + {\large + %\@date \par + \py@authoraddress \par + } + } + \end{flushright}%\par + \@thanks + \end{titlepage}% + \cleardoublepage% + \setcounter{footnote}{0}% + \let\thanks\relax\let\maketitle\relax + %\gdef\@thanks{}\gdef\@author{}\gdef\@title{} +} + +\fancypagestyle{normal}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\thepage}} + \fancyfoot[LO]{{\nouppercase{\rightmark}}} + \fancyfoot[RE]{{\nouppercase{\leftmark}}} + \fancyhead[LE,RO]{{ \@title, \py@release}} + \renewcommand{\headrulewidth}{0.4pt} + \renewcommand{\footrulewidth}{0.4pt} +} + +\fancypagestyle{plain}{ + \fancyhf{} + \fancyfoot[LE,RO]{{\thepage}} + \renewcommand{\headrulewidth}{0pt} + \renewcommand{\footrulewidth}{0.4pt} +} + +\titleformat{\section}{\Large}% + {\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\subsection}{\large}% + {\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\subsubsection}{}% + {\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor} +\titleformat{\paragraph}{\large}% + {\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor} + +\ChNameVar{\raggedleft\normalsize} +\ChNumVar{\raggedleft \bfseries\Large} +\ChTitleVar{\raggedleft \rm\Huge} + +\renewcommand\thepart{\@Roman\c@part} +\renewcommand\part{% + \pagestyle{plain} + \if@noskipsec \leavevmode \fi + \cleardoublepage + \vspace*{6cm}% + \@afterindentfalse + \secdef\@part\@spart} + +\def\@part[#1]#2{% + \ifnum \c@secnumdepth >\m@ne + \refstepcounter{part}% + \addcontentsline{toc}{part}{\thepart\hspace{1em}#1}% + \else + \addcontentsline{toc}{part}{#1}% + \fi + {\parindent \z@ %\center + \interlinepenalty \@M + \normalfont + \ifnum \c@secnumdepth >\m@ne + \rm\Large \partname~\thepart + \par\nobreak + \fi + \MakeUppercase{\rm\Huge #2}% + \markboth{}{}\par}% + \nobreak + \vskip 8ex + \@afterheading} +\def\@spart#1{% + {\parindent \z@ %\center + \interlinepenalty \@M + \normalfont + \huge \bfseries #1\par}% + \nobreak + \vskip 3ex + \@afterheading} + +% We want colored warning boxes +\renewcommand{\py@heavybox}{ + \setlength{\fboxrule}{1pt} + \setlength{\fboxsep}{6pt} + \setlength{\py@noticelength}{\linewidth} + \addtolength{\py@noticelength}{-2\fboxsep} + \addtolength{\py@noticelength}{-2\fboxrule} + %\setlength{\shadowsize}{3pt} + \color{warningcolor} + \Sbox + \minipage{\py@noticelength} + % After drawing the box, reset to black + \color{black} +} + + +% Font used for code snippets +\usepackage{beramono} + + +% XXX find a solution for this +% fix single quotes, for inconsolata. (does not work) +%%\usepackage{textcomp} +%%\begingroup +%% \catcode`'=\active +%% \g@addto@macro\@noligs{\let'\textsinglequote} +%% \endgroup +%%\endinput diff --git a/doc/sources/logo.pdf b/doc/sources/logo.pdf new file mode 100644 index 0000000000000000000000000000000000000000..94ccd9da3ab81b8b2e902da5553defb7ccfc0fcc GIT binary patch literal 4359 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 literal 0 HcmV?d00001 diff --git a/doc/sources/sphinxext/kivy_pygments_theme.py b/doc/sources/sphinxext/kivy_pygments_theme.py new file mode 100644 index 000000000..85eaa8477 --- /dev/null +++ b/doc/sources/sphinxext/kivy_pygments_theme.py @@ -0,0 +1,87 @@ +# kivy pygments style based on flask/tango style +from pygments.style import Style +from pygments.token import Keyword, Name, Comment, String, Error, \ + Number, Operator, Generic, Whitespace, Punctuation, Other, Literal + + +class KivyStyle(Style): + # The background color is set in kivystyle.sty + background_color = "" + default_style = "" + + styles = { + # No corresponding class for the following: + #Text: "", # class: '' + Whitespace: "underline #ffffff", # class: 'w' + Error: "#FF0000 border:#FF0000", # class: 'err' + Other: "#FF0000", # class 'x' + + Comment: "italic #aaa385", # class: 'c' + Comment.Preproc: "noitalic", # class: 'cp' + + Keyword: "bold #000000", # class: 'k' + Keyword.Constant: "bold #000000", # class: 'kc' + Keyword.Declaration: "bold #000000", # class: 'kd' + Keyword.Namespace: "bold #000000", # class: 'kn' + Keyword.Pseudo: "bold #000000", # class: 'kp' + Keyword.Reserved: "bold #000000", # class: 'kr' + Keyword.Type: "bold #000000", # class: 'kt' + + Operator: "#582800", # class: 'o' + Operator.Word: "bold #000000", # class: 'ow' - like keywords + + Punctuation: "bold #000000", # class: 'p' + + # because special names such as Name.Class, Name.Function, etc. + # are not recognized as such later in the parsing, we choose them + # to look the same as ordinary variables. + Name: "#000000", # class: 'n' + Name.Attribute: "#c4a000", # class: 'na' - to be revised + Name.Builtin: "#000000", # class: 'nb' + Name.Builtin.Pseudo: "#aa1105", # class: 'bp' + Name.Class: "#db6500", # class: 'nc' - to be revised + Name.Constant: "#000000", # class: 'no' - to be revised + Name.Decorator: "#888", # class: 'nd' - to be revised + Name.Entity: "#ce5c00", # class: 'ni' + Name.Exception: "bold #cc0000", # class: 'ne' + Name.Function: "#db6500", # class: 'nf' + Name.Property: "#000000", # class: 'py' + Name.Label: "#f57900", # class: 'nl' + Name.Namespace: "#000000", # class: 'nn' - to be revised + Name.Other: "#000000", # class: 'nx' + Name.Tag: "bold #004461", # class: 'nt' - like a keyword + Name.Variable: "#000000", # class: 'nv' - to be revised + Name.Variable.Class: "#000000", # class: 'vc' - to be revised + Name.Variable.Global: "#000000", # class: 'vg' - to be revised + Name.Variable.Instance: "#000000", # class: 'vi' - to be revised + + Number: "#990000", # class: 'm' + + Literal: "#000000", # class: 'l' + Literal.Date: "#000000", # class: 'ld' + + String: "#74171b", # class: 's' + String.Backtick: "#4e9a06", # class: 'sb' + String.Char: "#4e9a06", # class: 'sc' + String.Doc: "italic #640000", # class: 'sd' - like a comment + String.Double: "#74171b", # class: 's2' + String.Escape: "#74171b", # class: 'se' + String.Heredoc: "#74171b", # class: 'sh' + String.Interpol: "#74171b", # class: 'si' + String.Other: "#74171b", # class: 'sx' + String.Regex: "#74171b", # class: 'sr' + String.Single: "#74171b", # class: 's1' + String.Symbol: "#74171b", # class: 'ss' + + Generic: "#000000", # class: 'g' + Generic.Deleted: "#a40000", # class: 'gd' + Generic.Emph: "italic #000000", # class: 'ge' + Generic.Error: "#ef2929", # class: 'gr' + Generic.Heading: "bold #000080", # class: 'gh' + Generic.Inserted: "#00A000", # class: 'gi' + Generic.Output: "#888", # class: 'go' + Generic.Prompt: "#745334", # class: 'gp' + Generic.Strong: "bold #000000", # class: 'gs' + Generic.Subheading: "bold #800080", # class: 'gu' + Generic.Traceback: "bold #a40000", # class: 'gt' + } diff --git a/kivy/tools/pep8checker/pep8kivy.py b/kivy/tools/pep8checker/pep8kivy.py index 531d70a0e..cfebfd4ea 100644 --- a/kivy/tools/pep8checker/pep8kivy.py +++ b/kivy/tools/pep8checker/pep8kivy.py @@ -52,7 +52,7 @@ if __name__ == '__main__': errors = 0 pep8.process_options(['']) - exclude_dirs = ['/lib', '/coverage', '/pep8'] + exclude_dirs = ['/lib', '/coverage', '/pep8', '/doc'] exclude_files = ['kivy/gesture.py', 'osx/build.py', 'win32/build.py'] for target in targets: if os.path.isdir(target):