Fix Sphinx warnings and error (pdfminer#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 <[email protected]>

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
 

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
 

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:

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:

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: