Improve documentation build (#539)

* use imgconverter
* enable pdf build with xelatex
* change heading levels
* restructure headings
* add chapter intro
* remove extensions from index

.readthedocs.yml

@@ -1,6 +1,7 @@
 version: 2
 formats:
   - epub
+  - pdf
 build:
   os: ubuntu-22.04
   tools:
@@ -11,6 +12,7 @@ build:
     - gcc
     - libcups2-dev
     - python3-dev
+    - xindy
 sphinx:
   configuration: doc/conf.py
 submodules:

CHANGELOG.rst

@@ -1,6 +1,6 @@
-*********
 Changelog
-*********
+=========
+
 2023-05-11 - Version 3.0a9 - "Pride Comes Before A Fall"
 --------------------------------------------------------
 This release is the 10th alpha release of the new version 3.0.

CONTRIBUTING.rst

@@ -1,6 +1,5 @@
-************
 Contributing
-************
+============
 
 This project is open to any kind of contribution. You can help with improving the documentation, adding fixes to the
 code, providing test cases in code or as a description or just spreading the word. Please feel free to create an

README.rst

@@ -2,14 +2,13 @@
 python-escpos - Python library to manipulate ESC/POS Printers
 #############################################################
 
+Description
+===========
+
 .. image:: https://readthedocs.org/projects/python-escpos/badge/?version=latest
     :target: https://python-escpos.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
-
-Description
------------
-
 Python ESC/POS is a library which lets the user have access to all those printers handled
 by ESC/POS commands, as defined by Epson, from a Python application.
 

doc/conf.py

@@ -42,6 +42,7 @@ extensions = [
     "sphinx.ext.todo",
     "sphinx.ext.graphviz",
     "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.imgconverter",
     "sphinxcontrib.datatemplates",
     "sphinxcontrib.spelling",
 ]
@@ -68,7 +69,7 @@ master_doc = "index"
 
 # General information about the project.
 project = "python-escpos"
-copyright = "2016, Manuel F Martinez and others"
+copyright = "2023, python-escpos developers"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -224,6 +225,8 @@ latex_elements = {
     #'preamble': '',
 }
 
+latex_engine = "xelatex"
+
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
@@ -232,7 +235,7 @@ latex_documents = [
         "index",
         "python-escpos.tex",
         "python-escpos Documentation",
-        "Manuel F Martinez and others",
+        "python-escpos developers",
         "manual",
     ),
 ]
@@ -267,7 +270,7 @@ man_pages = [
         "index",
         "python-escpos",
         "python-escpos Documentation",
-        ["Manuel F Martinez and others"],
+        ["python-escpos developers"],
         1,
     )
 ]
@@ -286,7 +289,7 @@ texinfo_documents = [
         "index",
         "python-escpos",
         "python-escpos Documentation",
-        "Manuel F Martinez and others",
+        "python-escpos developers",
         "python-escpos",
         "One line description of project.",
         "Miscellaneous",

doc/dev/release-process.rst

@@ -1,6 +1,5 @@
-***************
 Release process
-***************
+===============
 
 * Update authors file
 * Update changelog

doc/dev/todo.rst

@@ -1,6 +1,5 @@
-****
 TODO
-****
+====
 
 Open points and issues of the project are tracked in the GitHub issues.
 Some annotations still remain in the code and should be moved over time

doc/index.rst

@@ -5,8 +5,15 @@
 
 .. include:: ../README.rst
 
+#######
 Content
--------
+#######
+
+User Documentation
+==================
+
+This chapter describes the central points that
+are relevant to the user of this library.
 
 .. toctree::
    :maxdepth: 1
@@ -19,13 +26,26 @@ Content
    user/usage
    user/barcode
 
+Printer profiles
+================
+
+This chapter gives a listing of the available
+printer profiles. Details are described in
+:ref:`capabilities-profile-intro`.
+
 .. toctree::
    :maxdepth: 1
    :caption: Printer profiles
 
-   printer_profiles/capabilities.rst
+   printer_profiles/capabilities
-   printer_profiles/available-profiles.rst
+   printer_profiles/available-profiles
-   printer_profiles/available-encodings.rst
+   printer_profiles/available-encodings
+
+Developer Documentation
+=======================
+
+This chapter summarizes information for
+developers of this library.
 
 .. toctree::
    :maxdepth: 1
@@ -36,6 +56,12 @@ Content
    dev/changelog
    dev/todo
 
+API Documentation
+=================
+
+This chapter contains an auto-generated
+documentation of the API of this library.
+
 .. toctree::
    :maxdepth: 1
    :caption: API Documentation
@@ -52,8 +78,9 @@ Content
    api/codepages
    api/katakana
 
+##################
 Indices and tables
-==================
+##################
 
 * :ref:`genindex`
 * :ref:`modindex`

doc/printer_profiles/capabilities.rst

@@ -1,3 +1,5 @@
+.. _capabilities-profile-intro:
+
 Capabilities
 ------------
 :Last Reviewed: 2023-07-29

doc/user/barcode.rst

@@ -1,5 +1,6 @@
 Printing Barcodes
 -----------------
+
 :Last Reviewed: 2023-05-16
 
 Many printers implement barcode printing natively.

doc/user/installation.rst

@@ -1,6 +1,5 @@
-************
 Installation
-************
+============
 
 :Last Reviewed: 2016-07-23
 

doc/user/methods.rst

@@ -1,6 +1,6 @@
-*******
 Methods
-*******
+=======
+
 :Last Reviewed: 2017-01-25
 
 Escpos class

doc/user/printers.rst

@@ -1,6 +1,6 @@
-********
 Printers
-********
+========
+
 :Last Reviewed: 2022-11-25
 
 As of now there are 7 different type of printer implementations.

doc/user/raspi.rst

@@ -1,6 +1,5 @@
-************
 Raspberry Pi
-************
+============
 
 :Last Reviewed: 2017-01-05
 

doc/user/usage.rst

@@ -1,6 +1,6 @@
-*****
 Usage
-*****
+=====
+
 :Last Reviewed: 2017-06-10
 
 Define your printer