From 86e34873e4daeb7329aa7420208e82f8d41e38b6 Mon Sep 17 00:00:00 2001
From: Chris Mayo <aklhfex@gmail.com>
Date: Tue, 24 May 2022 19:07:04 +0100
Subject: [PATCH] Fix Sphinx warnings and error (#760)

* Fix Sphinx warnings

howto/acro_forms.rst:4: WARNING: Title underline too short.
howto/acro_forms.rst:81: WARNING: Bullet list ends without a blank line; unexpected unindent.
howto/acro_forms.rst:88: WARNING: Bullet list ends without a blank line; unexpected unindent.
howto/acro_forms.rst:122: WARNING: Bullet list ends without a blank line; unexpected unindent.
tutorial/extract_pages.rst:6: WARNING: Failed to create a cross reference. A title or caption not found: api_extract_pages

* Fix documenting pdf2txt.py

reference/commandline.rst:12: ERROR: Module "tools.pdf2txt" has no attribute "maketheparser"
Incorrect argparse :module: or :func: values?

* Add CHANGELOG.md

Co-authored-by: Pieter Marsman <pietermarsman@gmail.com>
---
 CHANGELOG.md                          |  8 +++++++-
 docs/source/howto/acro_forms.rst      | 11 +++++++----
 docs/source/reference/commandline.rst |  2 +-
 docs/source/reference/highlevel.rst   |  4 ++--
 tools/pdf2txt.py                      |  8 ++++++--
 5 files changed, 23 insertions(+), 10 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 571bb13..e23fcf0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,7 +4,13 @@ All notable changes in pdfminer.six will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
-## [20220506]
+## [Unreleased]
+
+### Fixed
+
+- Sphinx errors during building of documentation ([#760](https://github.com/pdfminer/pdfminer.six/pull/760))
+
+## [20220524]
 
 ### Fixed
 
diff --git a/docs/source/howto/acro_forms.rst b/docs/source/howto/acro_forms.rst
index 23444ff..276dccf 100644
--- a/docs/source/howto/acro_forms.rst
+++ b/docs/source/howto/acro_forms.rst
@@ -1,7 +1,7 @@
 .. _acro_forms:
 
 How to extract AcroForm interactive form fields from a PDF using PDFMiner
-********************************
+*************************************************************************
 
 Before you start, make sure you have :ref:`installed pdfminer.six<install>`.
 
@@ -78,14 +78,16 @@ How it works:
     doc = PDFDocument(parser)
 
 - Get the catalog
-(the catalog contains references to other objects defining the document structure, see section 7.7.2 of PDF 32000-1:2008 specs: https://www.adobe.com/devnet/pdf/pdf_reference.html)
+
+  (the catalog contains references to other objects defining the document structure, see section 7.7.2 of PDF 32000-1:2008 specs: https://www.adobe.com/devnet/pdf/pdf_reference.html)
 
 .. code-block:: python
 
     res = resolve1(doc.catalog)
 
 - Check if the catalog contains the AcroForm key and raise ValueError if not 
-(the PDF does not contain Acroform type of interactive forms if this key is missing in the catalog, see section 12.7.2 of PDF 32000-1:2008 specs)
+
+  (the PDF does not contain Acroform type of interactive forms if this key is missing in the catalog, see section 12.7.2 of PDF 32000-1:2008 specs)
 
 .. code-block:: python
 
@@ -119,7 +121,8 @@ How it works:
     values = resolve1(value)
 
 - Call the value(s) decoding method as needed
-(a single field can hold multiple values, for example a combo box can hold more than one value at time)
+
+  (a single field can hold multiple values, for example a combo box can hold more than one value at time)
 
 .. code-block:: python
 
diff --git a/docs/source/reference/commandline.rst b/docs/source/reference/commandline.rst
index 7e4aba3..2195432 100644
--- a/docs/source/reference/commandline.rst
+++ b/docs/source/reference/commandline.rst
@@ -11,7 +11,7 @@ pdf2txt.py
 
 .. argparse::
     :module: tools.pdf2txt
-    :func: maketheparser
+    :func: create_parser
     :prog: python tools/pdf2txt.py
 
 .. _api_dumppdf:
diff --git a/docs/source/reference/highlevel.rst b/docs/source/reference/highlevel.rst
index b764e90..ef7ae76 100644
--- a/docs/source/reference/highlevel.rst
+++ b/docs/source/reference/highlevel.rst
@@ -21,10 +21,10 @@ extract_text_to_fp
 .. autofunction:: extract_text_to_fp
 
 
+.. _api_extract_pages:
+
 extract_pages
 =============
 
 .. currentmodule:: pdfminer.high_level
 .. autofunction:: extract_pages
-
-.. _api_extract_pages:
\ No newline at end of file
diff --git a/tools/pdf2txt.py b/tools/pdf2txt.py
index e872f5f..0511b93 100755
--- a/tools/pdf2txt.py
+++ b/tools/pdf2txt.py
@@ -63,7 +63,7 @@ def extract_text(
     return outfp
 
 
-def parse_args(args: Optional[List[str]]) -> argparse.Namespace:
+def create_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(description=__doc__, add_help=True)
     parser.add_argument(
         "files",
@@ -272,7 +272,11 @@ def parse_args(args: Optional[List[str]]) -> argparse.Namespace:
         "Only used when output_type is xml.",
     )
 
-    parsed_args = parser.parse_args(args=args)
+    return parser
+
+
+def parse_args(args: Optional[List[str]]) -> argparse.Namespace:
+    parsed_args = create_parser().parse_args(args=args)
 
     # Propagate parsed layout parameters to LAParams object
     if parsed_args.no_laparams: