doc: add latex and PDF generation to build_docs

Adds options for generating tex-files and PDFs when building documentation

Closes IDF-1217
Closes IDF-1464

docs/conf_common.py

@@ -66,6 +66,7 @@ extensions = ['breathe',
               'idf_extensions.run_doxygen',
               'idf_extensions.gen_idf_tools_links',
               'idf_extensions.format_idf_target',
+              'idf_extensions.latex_builder',
 
               # from https://github.com/pfalcon/sphinx_selective_exclude
               'sphinx_selective_exclude.eager_only',
@@ -293,48 +294,40 @@ html_static_path = ['../_static']
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ReadtheDocsTemplatedoc'
 
-
 # -- Options for LaTeX output ---------------------------------------------
 
+latex_template_dir = os.path.join(config_dir, 'latex_templates')
+
+preamble = ''
+with open(os.path.join(latex_template_dir, 'preamble.tex')) as f:
+    preamble = f.read()
+
+titlepage = ''
+with open(os.path.join(latex_template_dir, 'titlepage.tex')) as f:
+    titlepage = f.read()
+
+
 latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    # 'papersize': 'letterpaper',
-    #
-    # The font size ('10pt', '11pt' or '12pt').
-    # 'pointsize': '10pt',
-    #
+    'papersize': 'a4paper',
+
+    # Latex figure (float) alignment
+    'figure_align':'htbp',
+
+    'pointsize': '10pt',
+
     # Additional stuff for the LaTeX preamble.
-    # 'preamble': '',
+    'fncychap': '\\usepackage[Sonny]{fncychap}',
+
+    'preamble': preamble,
+
+    'maketitle': titlepage,
 }
 
-# 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 = [
-    ('index', 'ReadtheDocsTemplate.tex', u'Read the Docs Template Documentation',
-     u'Read the Docs', 'manual'),
-]
-
-# The name of an image file (relative to this directory) to place at the top of
+# The name of an image file (relative to this directory) to place at the bottom of
 # the title page.
-# latex_logo = None
-
-# For "manual" documents, if this is true, then toplevel headings are parts,
-# not chapters.
-# latex_use_parts = False
-
-# If true, show page references after internal links.
-# latex_show_pagerefs = False
-
-# If true, show URL addresses after external links.
-# latex_show_urls = False
-
-# Documents to append as an appendix to all manuals.
-# latex_appendices = []
-
-# If false, no module index is generated.
-# latex_domain_indices = True
-
+latex_logo = "../_static/espressif2.pdf"
+latex_engine = 'xelatex'
+latex_use_xindy = False
 
 # -- Options for manual page output ---------------------------------------
 
@@ -390,6 +383,22 @@ def setup(app):
 
     setup_diag_font(app)
 
+    # Config values pushed by -D using the cmdline is not available when setup is called
+    app.connect('config-inited',  setup_config_values)
+
+
+def setup_config_values(app, config):
+    # Sets up global config values needed by other extensions
+    idf_target_title_dict = {
+        'esp32': 'ESP32',
+        'esp32s2': 'ESP32-S2'
+    }
+
+    app.add_config_value('idf_target_title_dict', idf_target_title_dict, 'env')
+
+    pdf_name = "esp-idf-{}-{}-{}".format(app.config.language, app.config.version, app.config.idf_target)
+    app.add_config_value('pdf_file', pdf_name, 'env')
+
 
 def setup_diag_font(app):
     # blockdiag and other tools require a font which supports their character set