Put changelog in doc (#22)

* moved changelog to the documentation

* document utilities module

* change documentation theme

* change documentation theme

* renamed actions files

* bump version

* fix lint

Author: cbrunet

.github/workflows/pythonpackage.yml .github/workflows/build_and_test.yml.github/workflows/pythonpackage.yml renamed to .github/workflows/build_and_test.yml

@@ -1,18 +1 @@
-Changelog
-
-0.2.2
-- Bugfix: Document can be corrupted by garbage collector when created from data (or from file handle) (fixes #19)
-- Feature: Lower minimum required Python version to 3.6
-
-0.2.1
-- Bugfix: Fixed byte order in image format string used for Pillow
-- Bugfix: Prevent segmentation fault when performing some operations on locked documents (fixes #4)
-- Bugfix: Fix include paths in C++ (fixes #2)
-- Change namespace syntax to support old compilers (earlier than C++17) (fixes #6)
-
-0.2.0
-- Add the font infos to the TextBox object (Poppler 0.89.0)
-- Added __version__ to the Python package
-- Added buffer interface to Image
-- Added __str__ method to Image.Format enum, for interoperability with pillow
-- Bugfix: fixed the size of Image.data
+Changelog is now located at https://cbrunet.github.io/python-poppler/contribution.html

.github/workflows/pythonpublish.yml .github/workflows/publish.yml.github/workflows/pythonpublish.yml renamed to .github/workflows/publish.yml

@@ -0,0 +1,38 @@
+.. _changelog:
+
+Changelog
+=========
+
+0.2.2 (2020-10-03)
+------------------
+
+- Bugfix: Document can be corrupted by garbage collector when created from data (or from file handle) (Fixes :issue:`19`)
+- Bugfix: Fix build with some compilers (Fixes :issue:`17`)
+- Feature: Lower minimum required Python version to 3.6
+- Feature: Lower minimum required poppler version to 0.26.0 (See :pr:`13`)  -- by Sandeep Mistry
+
+0.2.1 (2020-06-19)
+------------------
+
+- Bugfix: Fixed byte order in image format string used for Pillow
+- Bugfix: Prevent segmentation fault when performing some operations on locked documents (Fixes :issue:`4`)
+- Bugfix: Fix include paths in C++ (Fixes :issue:`2`)
+- Change namespace syntax to support old compilers (earlier than C++17) (Fixes :issue:`6`)  -- by bnewbold
+
+0.2.0 (2020-06-04)
+------------------
+
+- Add the font infos to the :class:`.TextBox` object (Poppler 0.89.0)
+- Added `__version__` to the Python package
+- Added buffer interface to :class:`.Image`
+- Added `__str__` method to :class:`.Image.Format` enum, for interoperability with pillow
+- Bugfix: fixed the size of :attr:`.Image.data`
+
+0.1.x
+-----
+
+Project was still in development, and had no formal changelog.
+
+- 0.1.2: 2020-04-20
+- 0.1.1: 2020-04-20
+- 0.1.0: 2020-04-19 (initial version)

NEWS.txt

@@ -31,7 +31,9 @@
 extensions = [
     'sphinx.ext.autodoc',
     'sphinx.ext.githubpages',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.napoleon',
+    'sphinx_issues',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -48,22 +50,50 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'sphinx_material'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+# html_theme_options = {
+#     'description': "Python binding to poppler-cpp library, to read and render PDF documents.",
+#     'github_button': True,
+#     'github_user': 'cbrunet',
+#     'github_repo': 'python-poppler',
+#     'badge_branch': 'master',
+#     'extra_nav_links': {
+#         "GitHub": "https://github.com/cbrunet/python-poppler",
+#         "Issues tracker": "https://github.com/cbrunet/python-poppler/issues",
+#         "PyPI": "https://pypi.org/project/python-poppler/",
+#     }
+# }
+
 html_theme_options = {
-    'description': "Python binding to poppler-cpp library, to read and render PDF documents.",
-    'github_button': True,
-    'github_user': 'cbrunet',
-    'github_repo': 'python-poppler',
-    'badge_branch': 'master',
-    'extra_nav_links': {
-        "GitHub": "https://github.com/cbrunet/python-poppler",
-        "Issues tracker": "https://github.com/cbrunet/python-poppler/issues",
-        "PyPI": "https://pypi.org/project/python-poppler/",
-    }
+    'nav_title': "Python poppler",
+    'logo_icon': "&#x1F4D7",
+    'base_url': "https://cbrunet.github.io/python-poppler",
+    'repo_url': "https://github.com/cbrunet/python-poppler",
+    'repo_name': "python-poppler",
+
+    'globaltoc_depth': 2,
+    'globaltoc_collapse': False,
+    'globaltoc_includehidden': True,
+
+    'nav_links': [
+        {'title': "Issues tracker", 'href': "https://github.com/cbrunet/python-poppler/issues", 'internal': False},
+        {'title': "PyPI", 'href': "https://pypi.org/project/python-poppler/", 'internal': False},
+    ],
+
+}
+
+html_sidebars = {
+    "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"]
 }
+
+
+intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
+
+
+issues_github_path = "cbrunet/python-poppler"

docs/changelog.rst

@@ -7,7 +7,7 @@ Contributing
 Reporting bugs
 --------------
 
-Bugs are reported using the `Issue tracker on GitHub <https://github.com/cbrunet/python-poppler/issues>`.
+Bugs are reported using the `Issue tracker on GitHub <https://github.com/cbrunet/python-poppler/issues>`_.
 
 When you report a bug, try to be as specific as possible, and provide all the relevant information:
 
@@ -30,7 +30,7 @@ If you can, consider pull_request_.
 Requesting features
 -------------------
 
-Suggestions and feature requests can be submitted using the `Issue tracker on GitHub <https://github.com/cbrunet/python-poppler/issues>` as well.
+Suggestions and feature requests can be submitted using the `Issue tracker on GitHub <https://github.com/cbrunet/python-poppler/issues>`_ as well.
 
 However, you should understand that the main goal of **python-poppler** is to provide a Python binding
 to the poppler-cpp library. Therefore, if you need a feature that is not currently in poppler-cpp,
@@ -50,9 +50,9 @@ Pull requests are the prefered way for submitting patches, bug corrections, and
 When you submit a pull request, verify the following points:
 
 * You agree that the submitted code is under GPL 2.0 license;
-* Code is formatted using `black <https://github.com/psf/black>`. Ensure everything
+* Code is formatted using `black <https://github.com/psf/black>`_. Ensure everything
   is well formated, using `tox -e lint` command;
 * Please provide tests proving the bug is corrected, or covering the new feature, when it's possible;
 * Ensure that all unit tests pass, using the `tox` command;
-* Add a line to the changelog, in the NEWS.txt file;
+* Add a line to the changelog, in docs/changelog.rst;
 * Update the documentation, when it applies.

docs/conf.py

@@ -6,15 +6,6 @@
 python-poppler's documentation!
 ==========================================
 
-.. toctree::
-   :hidden:
-
-   installation
-   usage
-   contribution
-   api/modules
-
-
 **python-poppler** is a Python binding to the poppler-cpp library.
 It allows to read PDF documents, render them, and to modify some
 informations inside the documents.
@@ -45,6 +36,8 @@ Contents
 
 * :ref:`contributing` section is about submiting bugs or pull requests to the project.
 
+* :ref:`changelog` section gives informations about releases of the project.
+
 * :ref:`reference` lists all modules, classes, and methods. The reference section is still a work in progress...
 
 About poppler
@@ -107,11 +100,21 @@ poppler-glib
     You should use poppler-glib directly instead (see above).
 
 
+Detailed Contents
+------------------
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   usage
+   contribution
+   changelog
+   api/modules
+
+
 Indices and tables
 ------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
-

docs/contribution.rst

@@ -16,7 +16,7 @@
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 __author__ = "Charles Brunet"
-__version__ = "0.2.1"
+__version__ = "0.2.2"
 __version_info__ = tuple(map(int, __version__.split('.')))
 
 __all__ = ["__author__", "__version__", "__version_info__"]

docs/index.rst

@@ -15,34 +15,76 @@
 # with this program; if not, write to the Free Software Foundation, Inc.,
 # 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
+
+"""This module contains utility functions that are not part of
+poppler-cpp, but that helps interacting with it.
+"""
+
 from datetime import datetime
 import functools
 
 from poppler.cpp.version import version_major, version_minor, version_micro
 
 
 def from_time_type(timestamp):
+    """Convert a timestamp to a :class:`datetime.datetime` object.
+
+    Args:
+        timestamp (int): a positive integer, to be interpreted as 32 bits complement 2.
+
+    Returns:
+        Optional[datetime.datetime]: the date and time,
+                                     or None if the timestamp is equivalent to -1.
+
+    """
     if timestamp == 2 ** 32 - 1:
         return None
     return datetime.fromtimestamp(timestamp)
 
 
 def to_time_type(date_time):
+    """Convert a Python :class:`datetime.datetime` object
+    to a timestamp compatible with poppler.
+
+    Args:
+        date_time (Optional[datetime.datetime]): the date and time, or None
+
+    Returns:
+        int: the timestamp
+
+    """
     return int(date_time.timestamp()) if date_time else 2 ** 32 - 1
 
 
 def version():
+    """Get poppler version, as a tuple
+
+    Returns:
+        Tuple[int, int, int]: (major, minor, micro)
+
+    """
     return version_major(), version_minor(), version_micro()
 
 
-def since(maj, min):
+def since(major, minor):
+    """Decorator used to mark the minimum required version of poppler
+    needed to execute a function.
+
+    If poppler version is lower than the specified version,
+    it raises a NotImplementedError when called.
+
+    Args:
+        major (int): major version number
+        minor (int): minor version number
+
+    """
     def wrapper(fct):
         @functools.wraps(fct)
         def wrapped(*args, **kwargs):
-            if version() < (maj, min, 0):
+            if version() < (major, minor, 0):
                 raise NotImplementedError(
                     "This functionality requires at least Poppler version {}".format(
-                        ".".join(map(str, (maj, min, 0)))
+                        ".".join(map(str, (major, minor, 0)))
                     )
                 )
             return fct(*args, **kwargs)

src/poppler/_version.py

@@ -15,6 +15,8 @@ commands =
 
 deps = 
     sphinx
+    sphinx-issues
+    sphinx-material
     ghp-import
 commands =
     sphinx-apidoc -o docs/api --separate --module-first src/poppler src/poppler/cpp/
@@ -53,6 +55,8 @@ deps =
     flake8
     flake8-bugbear
     sphinx
+    sphinx-issues
+    sphinx-material
 
 
 [flake8]