Improves Documentation (#58)

* fix missing bullet points
* fix the CI: Fetch `gh-pages` branch and tags before generating `versions.txt` when building docs.
* update doc dependencies

Co-authored-by: real-yfprojects <[email protected]>

.github/actions/publish-docs/action.yml

@@ -23,6 +23,10 @@ runs:
         ls -la ".github/pages/${GITHUB_REF##*/}"
       shell: bash
 
+    - name: Fetch remote
+      run: git fetch origin -t gh-pages
+      shell: bash
+
     - name: Write versions.txt
       run: poetry run sphinx_rtd_theme_github_versions .github/pages
       shell: bash

README.rst

@@ -96,28 +96,34 @@ A comparison will likely change over time.
 As in Oct, 2022, in my personal opinion (johannesjh),
 I see the following similarities and differences:
 
--  Both projects generate build modules for flatpak-builder.
--  Both projects consist of a single script file with minimal
+*  Both projects generate build modules for flatpak-builder.
+
+*  Both projects consist of a single script file with minimal
    dependencies, and are thus very easy to install.
--  ``flatpak-pip-generator`` resolves dependencies and freezes
+
+*  ``flatpak-pip-generator`` resolves dependencies and freezes
    dependency versions, whereas ``req2flatpak.py`` asks the user to
    provide a fully resolved list of dependencies with frozen dependency
    versions. Various tools exist which make this easy, e.g.,
    pip, pip-compile and poetry.
--  ``flatpak-pip-generator`` is older and thus likely to be more mature.
+
+*  ``flatpak-pip-generator`` is older and thus likely to be more mature.
    It supports more commandline options and probably has a more complete
    feature set.
--  ``req2flatpak.py`` is faster. The script itself runs faster because
+
+*  ``req2flatpak.py`` is faster. The script itself runs faster because
    it does not need to download package files in order to generate the
    build module. And the flatpak build runs faster because all packages
    (from the entire ``requirements.txt`` file) are installed in a single
    call to ``pip install``.
--  ``req2flatpak.py`` re-implements some functionality of pip. In
+
+*  ``req2flatpak.py`` re-implements some functionality of pip. In
    contrast, ``flatpak-pip-generator`` uses pip’s official
    functionality. Specifically, ``req2flatpak.py`` re-implements how pip
    queries available downloads from pypi and how pip chooses suitable
    downloads to match a given target platform.
--  ``req2flatpak.py`` prefers binary wheels, whereas
+
+*  ``req2flatpak.py`` prefers binary wheels, whereas
    ``flatpak-pip-generator`` prefers source packages.
 
 License

docs/source/api.rst

@@ -37,7 +37,9 @@ to modify each step as you see fit.
 For example:
 
 * you may want to query other package indices instead of pypi,
+
 * you may prefer wheels or sdists for certain packages, or
+
 * you may want to exclude specific packages.
 
 The following subsections explain in detail how you can use req2flatpak's python api in your custom script.

docs/source/development.rst

@@ -27,6 +27,7 @@ It can be useful to install a specific (older) version of python
 to make sure req2flatpak stays compatible with older targeted python versions.
 
 * Python versions targeted by req2flatpak are defined in the ``pyproject.toml`` file.
+
 * You can use `pyenv <https://github.com/pyenv/pyenv>`__
   to install various python versions for use in a virtual environment.
   It is a good practice to install and use the oldest still supported python version
@@ -40,7 +41,9 @@ Simply clone/open req2flatpak in the IDE of your choice.
 Features and languages that the IDE should ideally support include:
 
 * python
+
 * poetry for managing req2flatpak's dependencies in a virtual environment
+
 * restructured text (``*.rst``) for writing documentation
 
 
@@ -204,7 +207,11 @@ Publishing a Release
 Use the following steps to publish a release of req2flatpak:
 
 * Enter the version number to be released in ``pyproject.toml``, e.g., ``version = "1.2.3"``. Commit and push this change to a branch and create a merge request.
+
 * Describe the release in ``docs/source/changelog.rst``. Commit and push the modified changelog in the same branch.
+
 * Verify that the branch builds correctly. Ideally run some manual tests. Optionally tag a release candidate by pushing a tag such as v1.2.3-rc1. If the quality looks good, merge the branch.
+
 * Tag the main branch with the version to be released, e.g., push a tag named ``v1.2.3``.
+
 * Github CI will build the python package and publish it on PyPI.

docs/source/index.rst

@@ -21,5 +21,7 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
+
 * :ref:`modindex`
+
 * :ref:`search`