Sphinx-based documentation (#17)

Co-authored-by: Bernát Gábor <gaborjbernat@gmail.com>

.github/workflows/check.yml

@@ -86,6 +86,7 @@ jobs:
         tox_env:
           - dev
           - pkg_check
+          - docs
         exclude:
           - { os: windows, tox_env: pkg_check }
     steps:

.readthedocs.yml

@@ -0,0 +1,18 @@
+version: 2
+build:
+  image: latest
+formats:
+  - htmlzip
+  - epub
+  - pdf
+python:
+   version: 3.7
+   install:
+      - method: pip
+        path: .
+        extra_requirements:
+            - docs
+sphinx:
+  builder: html
+  configuration: docs/conf.py
+  fail_on_warning: true

README.rst

@@ -4,8 +4,11 @@ the problem
 .. image:: https://github.com/platformdirs/platformdirs/workflows/Test/badge.svg
    :target: https://github.com/platformdirs/platformdirs/actions?query=workflow%3ATest
 
-What directory should your app use for storing user data? If running on macOS, you
-should use::
+When writing desktop application, finding the right location to store user data
+and configuration varies per platform. Even for single-platform apps, there
+may by plenty of nuances in figuring out the right location.
+
+For example, if running on macOS, you should use::
 
     ~/Library/Application Support/<AppName>
 
@@ -19,11 +22,11 @@ or possibly::
 
 for `roaming profiles <https://docs.microsoft.com/en-us/previous-versions/windows/it-pro/windows-vista/cc766489(v=ws.10)>`_ but that is another story.
 
-On Linux (and other Unices) the dir, according to the `XDG
-spec <https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_, is::
+On Linux (and other Unices), according to the `XDG Basedir Spec`_, it should be::
 
     ~/.local/share/<AppName>
 
+.. _XDG Basedir Spec: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
 
 ``platformdirs`` to the rescue
 ==============================
@@ -38,17 +41,18 @@ This kind of thing is what the ``platformdirs`` module is for.
 - site config dir (``site_config_dir``)
 - user log dir (``user_log_dir``)
 
-and also:
+And also:
 
-- is a single module so other Python packages can include their own private copy
-- is slightly opinionated on the directory names used. Look for "OPINION" in
+- Is a single module so other Python packages can vendor their own private copy.
+- Is slightly opinionated on the directory names used. Look for "OPINION" in
   documentation and code for when an opinion is being applied.
 
+Example output
+==============
 
-some example output
-===================
+On macOS:
 
-On macOS::
+.. code-block:: pycon
 
     >>> from platformdirs import *
     >>> appname = "SuperApp"
@@ -62,7 +66,9 @@ On macOS::
     >>> user_log_dir(appname, appauthor)
     '/Users/trentm/Library/Logs/SuperApp'
 
-On Windows 7::
+On Windows 7:
+
+.. code-block:: pycon
 
     >>> from platformdirs import *
     >>> appname = "SuperApp"
@@ -76,7 +82,9 @@ On Windows 7::
     >>> user_log_dir(appname, appauthor)
     'C:\\Users\\trentm\\AppData\\Local\\Acme\\SuperApp\\Logs'
 
-On Linux::
+On Linux:
+
+.. code-block:: pycon
 
     >>> from platformdirs import *
     >>> appname = "SuperApp"
@@ -103,7 +111,7 @@ On Linux::
 ``PlatformDirs`` for convenience
 ================================
 
-::
+.. code-block:: pycon
 
     >>> from platformdirs import PlatformDirs
     >>> dirs = PlatformDirs("SuperApp", "Acme")
@@ -116,8 +124,6 @@ On Linux::
     >>> dirs.user_log_dir
     '/Users/trentm/Library/Logs/SuperApp'
 
-
-
 Per-version isolation
 =====================
 
@@ -136,9 +142,11 @@ dirs::
     >>> dirs.user_log_dir
     '/Users/trentm/Library/Logs/SuperApp/1.0'
 
+Be wary of using this for configuration files though; you'll need to handle
+migrating configuration files manually.
 
-Why the Fork?
-=============
+Why this Fork?
+==============
 
 This repository is a friendly fork of the wonderful work started by
 `ActiveState <https://github.com/ActiveState/appdirs>`_ who created

docs/api.rst

@@ -0,0 +1,56 @@
+API
+===
+
+.. note::
+   On Unix / Linux, we follow the `XDG Basedir Spec`_. The spec allows overriding
+   directories with environment variables. The examples show are the default
+   values, alongside the name of the environment variable that overrides them.
+
+   See the spec itself for further details on the topic.
+
+.. _XDG Basedir Spec: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
+
+User directories
+~~~~~~~~~~~~~~~~
+
+These are user-specific (and, generally, user-writeable) directories.
+
+User data directory
+-------------------
+
+.. autofunction:: platformdirs.user_data_dir
+
+User config directory
+---------------------
+
+.. autofunction:: platformdirs.user_config_dir
+
+Cache directory
+-------------------
+
+.. autofunction:: platformdirs.user_cache_dir
+
+State directory
+-------------------
+
+.. autofunction:: platformdirs.user_state_dir
+
+Logs directory
+-------------------
+
+.. autofunction:: platformdirs.user_log_dir
+
+Shared directories
+~~~~~~~~~~~~~~~~~~
+
+These are system-wide (and, generally, read-only) directories.
+
+Shared data directory
+---------------------
+
+.. autofunction:: platformdirs.site_data_dir
+
+Shared config directory
+-----------------------
+
+.. autofunction:: platformdirs.site_config_dir

docs/changelog.rst

@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst

docs/conf.py

@@ -0,0 +1,13 @@
+from platformdirs.version import __version__
+
+author = "The platformdirs team"
+project = "platformdirs"
+copyright = "2021, The platformdirs team"
+
+release = __version__
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosectionlabel",
+    "sphinx.ext.viewcode",
+]
+html_theme = "furo"

docs/index.rst

@@ -0,0 +1,20 @@
+platformdirs's documentation
+============================
+
+`platformdirs` is a library to determine platform-specific system directories.
+This includes directories where to place cache files, user data, configuration,
+etc.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   api
+   changelog
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

setup.cfg

@@ -40,6 +40,10 @@ zip_safe = True
 where = src
 
 [options.extras_require]
+docs =
+    Sphinx>=4.1.1,<5.0.0
+    furo>=2021.7.5b38
+    proselint>=0.10.2
 test =
     appdirs@https://github.com/ActiveState/appdirs/archive/8eacfa312d77aba28d483fbfb6f6fc54099622be.zip
     pytest>=6