Merge pull request #155 from Mulugruntz/sgiffard/documentation

Fix documentation

.github/workflows/build.yml

@@ -110,7 +110,7 @@ jobs:
         uses: actions/setup-python@v4
 
       - id: prepare-sphinx
-        run: pip install sphinx==4.5.0 sphinx-rtd-theme==1.0.0
+        run: pip install -r pr/requirements.docs.txt
 
       - id: run-sphinx
         run: sphinx-build -b html pr/docs gh-pages -E -d $GITHUB_WORKSPACE/.doctree

.github/workflows/publish-pypi.yaml

@@ -42,6 +42,6 @@ jobs:
         test $(git for-each-ref --format='%(objecttype)' ${GITHUB_REF}) == tag
     - name: Publish distribution to PyPI
       if: startsWith(github.ref, 'refs/tags')
-      uses: pypa/gh-action-pypi-publish@master
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
         password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/sphinx.yml

@@ -31,7 +31,7 @@ jobs:
         uses: actions/setup-python@v4
 
       - name: "Install Sphinx & Theme"
-        run: pip install sphinx==4.5.0 sphinx-rtd-theme==1.0.0
+        run: pip install -r main/requirements.docs.txt
 
       - name: "Run Sphinx"
         run: sphinx-build -b html main/docs gh-pages -E -d $GITHUB_WORKSPACE/.doctree

Makefile

@@ -6,6 +6,7 @@ long_ver = $(shell git describe --long 2>/dev/null | cut -f2 -d/ || echo $(short
 PYTHON ?= python3
 PYTHON_SOURCE_DIRS = rohmu/ test/
 PYTEST_ARG ?= -v
+RST_FILES = README.rst docs/about.rst docs/autodoc.rst docs/development.rst docs/index.rst docs/toc.rst docs/usage.rst
 
 .PHONY: fedora-dev-setup
 fedora-dev-setup:
@@ -37,7 +38,7 @@ mypy:
 fmt:
 	isort $(PYTHON_SOURCE_DIRS)
 	black $(PYTHON_SOURCE_DIRS)
-	$(PYTHON) -m rstfmt README.rst -w 100
+	$(PYTHON) -m rstfmt $(RST_FILES) -w 100
 
 .PHONY: coverage
 coverage:

README.rst

@@ -1,3 +1,10 @@
+#######
+ Rohmu
+#######
+
+..
+   start-include-intro
+
 |Rohmu logo|
 
 |Build badge| |PyPI badge| |Python versions badge|
@@ -8,75 +15,145 @@ supports main public clouds such as GCP, AWS, and Azure for backup storage. Rohm
 backup tools such as PGHoard_ for PostgreSQL, MyHoard_ for MySQL, and Astacus_ for M3, ClickHouse,
 and other databases.
 
-##########
+..
+   end-include-intro
+
+..
+   start-include-features
+
+**********
  Features
-##########
+**********
 
 -  Supported object storages: Azure, GCP, S3, Swift (OpenStack), local file storage, and SFTP.
 -  Supported compression algorithms: Snappy_, zstd_, and lzma_.
 
-##############
+..
+   end-include-features
+
+..
+   start-include-requirements
+
+**************
  Requirements
-##############
+**************
 
 Rohmu requires Python >= 3.8. For Python library dependencies, refer to setup.cfg_.
 
-###############
+..
+   end-include-requirements
+
+..
+   start-include-usage
+
+***************
  Usage example
-###############
+***************
 
 *Add usage example here*
 
 For real-world usage, see `how Rohmu is used in PGHoard`_.
 
-#############
+..
+   end-include-usage
+
+*************
  Development
-#############
+*************
 
 *TODO*
 
-#########
+..
+   start-include-building-the-package
+
+**********************
+ Building the package
+**********************
+
+To build an installation package for your distribution, go to the root directory of a Rohmu Git
+checkout and run:
+
+Fedora:
+
+.. code::
+
+   sudo make fedora-dev-setup
+   make rpm
+
+This will produce a ``.rpm`` package usually into ``rpm/RPMS/noarch/``.
+
+..
+   end-include-building-the-package
+
+..
+   start-include-license
+
+*********
  License
-#########
+*********
 
 Rohmu is licensed under the Apache license, version 2.0. Full license text is available in the
 LICENSE_ file.
 
 Please note that the project explicitly does not require a CLA (Contributor License Agreement) from
 its contributors.
 
-############
+..
+   end-include-license
+
+..
+   start-include-trademarks-and-credits
+
+************
  Trademarks
-############
+************
 
 PostgreSQL, MySQL, M3 and ClickHouse are trademarks and property of their respective owners. All
 product and service names used in this website are for identification purposes only and do not imply
 endorsement.
 
-#########
+*********
  Credits
-#########
+*********
 
 Rohmu was created by and is maintained by Aiven_.
 
 Rohmu was originally a part of PGHoard_ but was later extracted to its own GitHub project.
 
 The Rohmu logo was created by `@evche-aiven`_.
 
-#########
+..
+   end-include-trademarks-and-credits
+
+..
+   start-include-contact
+
+*********
  Contact
-#########
+*********
 
 Bug reports and patches are very welcome; please post them as GitHub issues and pull requests at
 rohmu_repo_. To report any possible vulnerabilities or other serious issues, please see our
 security_ policy.
 
-###########
+..
+   end-include-contact
+
+..
+   start-include-copyright
+
+***********
  Copyright
-###########
+***********
 
 Copyright (C) 2023 Aiven Ltd and contributors to the Rohmu project.
 
+..
+   end-include-copyright
+
+..
+   start-include-links
+
 ..
    --------- Links ---------
 

docs/about.rst

@@ -1,12 +1,10 @@
-About Rohmu
-===========
+#############
+ About Rohmu
+#############
 
-Features
---------
-
-*  Supported object storages: Azure, GCP, S3, Swift (OpenStack), local
-   file storage and SFTP.
-*  Supported compression algorithms: Snappy,
-   `zstd <https://github.com/facebook/zstd>`__ and
-   `lzma <https://docs.python.org/3/library/lzma.html>`__.
+.. include:: ../README.rst
+   :start-after: start-include-features
+   :end-before: end-include-features
 
+.. include:: ../README.rst
+   :start-after: start-include-links

docs/api__object_storage.rst

@@ -0,0 +1,61 @@
+
+
+Azure
+=====
+
+.. autopydantic_model:: rohmu.object_storage.config.AzureObjectStorageConfig
+
+.. autoclass:: rohmu.object_storage.azure.AzureTransfer
+   :members:
+
+
+Google
+======
+
+.. autopydantic_model:: rohmu.object_storage.config.GoogleObjectStorageConfig
+
+.. autoclass:: rohmu.object_storage.google.GoogleTransfer
+   :members:
+
+.. autoclass:: rohmu.object_storage.google.MediaStreamUpload
+   :members:
+
+.. autoclass:: rohmu.object_storage.google.MediaIoBaseDownloadWithByteRange
+   :members:
+
+
+Local
+=====
+
+.. autopydantic_model:: rohmu.object_storage.config.LocalObjectStorageConfig
+
+.. autoclass:: rohmu.object_storage.local.LocalTransfer
+   :members:
+
+
+S3
+==
+
+.. autopydantic_model:: rohmu.object_storage.config.S3ObjectStorageConfig
+
+.. autoclass:: rohmu.object_storage.s3.S3Transfer
+   :members:
+
+
+SFTP
+====
+
+.. autopydantic_model:: rohmu.object_storage.config.SFTPObjectStorageConfig
+
+.. autoclass:: rohmu.object_storage.sftp.SFTPTransfer
+   :members:
+
+
+Swift
+=====
+
+.. autopydantic_model:: rohmu.object_storage.config.SwiftObjectStorageConfig
+
+.. autoclass:: rohmu.object_storage.swift.SwiftTransfer
+   :members:
+

docs/autodoc.rst

@@ -0,0 +1,87 @@
+##########################
+ Python API Documentation
+##########################
+
+********
+ Common
+********
+
+.. autoclass:: rohmu.BaseTransfer
+
+.. autofunction:: rohmu.get_class_for_notifier
+
+.. autofunction:: rohmu.get_class_for_storage_driver
+
+.. autofunction:: rohmu.get_class_for_transfer
+
+.. autofunction:: rohmu.get_notifier
+
+.. autofunction:: rohmu.get_transfer_from_model
+
+.. autofunction:: rohmu.get_transfer_model
+
+.. autofunction:: rohmu.get_transfer
+
+.. autoclass:: rohmu.Notifier
+
+.. autoclass:: rohmu.ProxyInfo
+
+.. autodata:: rohmu.S3AddressingStyle
+
+.. autoclass:: rohmu.StorageDriver
+
+.. autoclass:: rohmu.StorageModel
+
+***************
+ Delta Backups
+***************
+
+.. automodule:: rohmu.delta
+   :members:
+
+.. automodule:: rohmu.delta.common
+   :members:
+
+.. automodule:: rohmu.delta.snapshot
+   :members:
+
+***********
+ Notifiers
+***********
+
+.. automodule:: rohmu.notifier
+   :members:
+
+.. automodule:: rohmu.notifier.interface
+   :members:
+
+HTTP Notifier
+=============
+
+.. automodule:: rohmu.notifier.http
+   :members:
+
+Logger Notifier
+===============
+
+.. automodule:: rohmu.notifier.logger
+   :members:
+
+Null Notifier
+=============
+
+.. automodule:: rohmu.notifier.null
+   :members:
+
+*****************
+ Object Storages
+*****************
+
+.. include:: api__object_storage.rst
+
+************
+ Exceptions
+************
+
+.. automodule:: rohmu.errors
+   :members: