From 968afafc5ca28385d1ea719861e49992e042307e Mon Sep 17 00:00:00 2001 From: Hugo Osvaldo Barrera Date: Sat, 17 Jul 2021 00:33:36 +0200 Subject: [PATCH] Sphinx-based documentation (#17) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Bernát Gábor --- .github/workflows/check.yml | 1 + .readthedocs.yml | 18 ++ README.rst | 42 ++-- docs/api.rst | 56 ++++++ docs/changelog.rst | 1 + docs/conf.py | 13 ++ docs/index.rst | 20 ++ setup.cfg | 4 + src/platformdirs/__init__.py | 362 +++++++++++++++++++---------------- tox.ini | 8 + 10 files changed, 341 insertions(+), 184 deletions(-) create mode 100644 .readthedocs.yml create mode 100644 docs/api.rst create mode 100644 docs/changelog.rst create mode 100644 docs/conf.py create mode 100644 docs/index.rst diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index f1076db6..32a00a34 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -86,6 +86,7 @@ jobs: tox_env: - dev - pkg_check + - docs exclude: - { os: windows, tox_env: pkg_check } steps: diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 00000000..dbdc904b --- /dev/null +++ b/.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 diff --git a/README.rst b/README.rst index ee2fd4a8..b35d9688 100644 --- a/README.rst +++ b/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/ @@ -19,11 +22,11 @@ or possibly:: for `roaming profiles `_ but that is another story. -On Linux (and other Unices) the dir, according to the `XDG -spec `_, is:: +On Linux (and other Unices), according to the `XDG Basedir Spec`_, it should be:: ~/.local/share/ +.. _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 `_ who created diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 00000000..4cfcf5d0 --- /dev/null +++ b/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 diff --git a/docs/changelog.rst b/docs/changelog.rst new file mode 100644 index 00000000..d9e113ec --- /dev/null +++ b/docs/changelog.rst @@ -0,0 +1 @@ +.. include:: ../CHANGES.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..2cbaf7b4 --- /dev/null +++ b/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" diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..eca432ce --- /dev/null +++ b/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` diff --git a/setup.cfg b/setup.cfg index 0f12acf0..ee80a4a6 100644 --- a/setup.cfg +++ b/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 diff --git a/src/platformdirs/__init__.py b/src/platformdirs/__init__.py index 654b4d36..db06bb0f 100644 --- a/src/platformdirs/__init__.py +++ b/src/platformdirs/__init__.py @@ -1,6 +1,5 @@ # Copyright (c) 2005-2010 ActiveState Software Inc. # Copyright (c) 2013 Eddy Petrișor - """Utilities for determining application-specific dirs. See for details and usage. @@ -8,9 +7,8 @@ # Dev Notes: # - MSDN on where to store app data files: # http://support.microsoft.com/default.aspx?scid=kb;en-us;310294#XSLTH3194121123120121120120 -# - Mac OS X: http://developer.apple.com/documentation/MacOSX/Conceptual/BPFileSystem/index.html +# - macOS: http://developer.apple.com/documentation/MacOSX/Conceptual/BPFileSystem/index.html # - XDG spec for Un*x: https://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html - import os import sys @@ -328,240 +326,270 @@ def _user_log_dir_impl(appname=None, appauthor=None, version=None, opinion=True) return path -def user_data_dir(appname=None, appauthor=None, version=None, roaming=False): +def user_data_dir(appname: str = None, appauthor: str = None, version: str = None, roaming: bool = False): r"""Return full path to the user-specific data dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "roaming" (boolean, default False) can be set True to use the Windows - roaming appdata directory. That means that for users on a Windows - network setup for roaming profiles, this user data will be - sync'd on login. See - - for a discussion of issues. + :param appname: The name of application. + If ``None``, just the system directory is returned. + :param appauthor: (only used on Windows) The name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass ``False`` to disable it. + :param version: An optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ``.``. + + Only applied when appname is present. + :param roaming: Whether to use the roaming appdata directory on Windows. That means + that for users on a Windows network setup for roaming profiles, this user data + will be sync'd on login. See + http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx for a discussion + of issues. Typical user data directories are: - Mac OS X: ~/Library/Application Support/ - Unix: ~/.local/share/ # or in $XDG_DATA_HOME, if defined - Win XP (not roaming): C:\Documents and Settings\\Application Data\\ - Win XP (roaming): C:\Documents and Settings\\Local Settings\Application Data\\ - Win 7 (not roaming): C:\Users\\AppData\Local\\ - Win 7 (roaming): C:\Users\\AppData\Roaming\\ - - For Unix, we follow the XDG spec and support $XDG_DATA_HOME. - That means, by default "~/.local/share/". + + | **macOS**: + | ``~/Library/Application Support/$appname`` + | **Unix / Linux**: + | ``~/.local/share/$appname`` (or ``$XDG_DATA_HOME/$appname``) + | **Win XP (not roaming)**: + | ``%USERPROFILE%\Application Data\$appauthor\$appname`` + | **Win XP (roaming)**: + | ``%USERPROFILE%\Local Settings\Application Data\$appauthor\$appname`` + | **Win 7 (not roaming)**: + | ``%USERPROFILE%\AppData\Local\$appauthor\$appname`` + | **Win 7 (roaming)**: + | ``%USERPROFILE%\AppData\Roaming\$appauthor\$appname`` + + For Unix, we follow the XDG basedir spec and support ``$XDG_DATA_HOME``. """ return _user_data_dir_impl(appname=appname, appauthor=appauthor, version=version, roaming=roaming) -def site_data_dir(appname=None, appauthor=None, version=None, multipath=False): +def site_data_dir(appname: str = None, appauthor: str = None, version: str = None, multipath: bool = False): r"""Return full path to the user-shared data dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "multipath" is an optional parameter only applicable to *nix - which indicates that the entire list of data dirs should be - returned. By default, the first item from XDG_DATA_DIRS is - returned, or '/usr/local/share/', - if XDG_DATA_DIRS is not set + :param appname: The name of application. + If ``None``, just the base directory is returned. + :param appauthor: (only used on Windows) The name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass ``False`` to disable it. + :param version: An optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ".". + Only applied when appname is present. + :param multipath: An optional parameter only applicable to \*nix + which indicates that the entire list of data dirs should be + returned. By default, the first item from ``XDG_DATA_DIRS`` is + returned, or ``/usr/local/share/$appname`` if ``XDG_DATA_DIRS`` is not set Typical site data directories are: - Mac OS X: /Library/Application Support/ - Unix: /usr/local/share/ or /usr/share/ - Win XP: C:\Documents and Settings\All Users\Application Data\\ - Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.) - Win 7: C:\ProgramData\\ # Hidden, but writeable on Win 7. - For Unix, this is using the $XDG_DATA_DIRS[0] default. + | **macOS**: + | ``/Library/Application Support/$appname`` + | **Unix / Linux**: + | ``/usr/local/share/$appname`` or ``/usr/share/$appname`` + | **Win XP**: + | ``%USERPROFILE%\Application Data\$appauthor\$appname`` + | **Win Vista**: + | Fails, ``C:\ProgramData`` is a hidden *system* directory + | **Win 7**: + | ``C:\ProgramData\$appauthor\$appname`` + + For Unix, this is using the ``$XDG_DATA_DIRS[0]`` default. WARNING: Do not use this on Windows. See the Vista-Fail note above for why. """ return _site_data_dir_impl(appname=appname, appauthor=appauthor, version=version, multipath=multipath) -def user_config_dir(appname=None, appauthor=None, version=None, roaming=False): +def user_config_dir(appname: str = None, appauthor: str = None, version: str = None, roaming: bool = False): r"""Return full path to the user-specific config dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "roaming" (boolean, default False) can be set True to use the Windows - roaming appdata directory. That means that for users on a Windows - network setup for roaming profiles, this user data will be - sync'd on login. See - - for a discussion of issues. + :param appname: The name of application. + If None, just the system directory is returned. + :param appauthor: (only used on Windows) The name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass False to disable it. + :param version: An optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ".". + Only applied when appname is present. + :param roaming: Whether to use the Windows roaming appdata directory. That means + that for users on a Windows network setup for roaming profiles, this user data + will be sync'd on login. + + See http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx for a + discussion of issues. Typical user config directories are: - Mac OS X: ~/Library/Preferences/ - Unix: ~/.config/ # or in $XDG_CONFIG_HOME, if defined - Win *: same as user_data_dir - For Unix, we follow the XDG spec and support $XDG_CONFIG_HOME. - That means, by default "~/.config/". + | **macOS**: + | ``~/Library/Preferences/$appname`` + | **Unix / Linux**: + | ``~/.config/$appname`` (or ``$XDG_CONFIG_HOME/$appname``) + | **Win XP (not roaming)**: + | Same as :func:`~.user_data_dir`. + + For Unix, we follow the XDG basedir spec and use ``$XDG_CONFIG_HOME``. """ return _user_config_dir_impl(appname=appname, appauthor=appauthor, version=version, roaming=roaming) -def site_config_dir(appname=None, appauthor=None, version=None, multipath=False): +def site_config_dir(appname: str = None, appauthor: str = None, version: str = None, multipath: bool = False): r"""Return full path to the user-shared data dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "multipath" is an optional parameter only applicable to *nix - which indicates that the entire list of config dirs should be - returned. By default, the first item from XDG_CONFIG_DIRS is - returned, or '/etc/xdg/', if XDG_CONFIG_DIRS is not set + :param appname: is the name of application. + If None, just the system directory is returned. + :param appauthor: (only used on Windows) is the name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass False to disable it. + :param version: is an optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ".". + Only applied when appname is present. + :param multipath: is an optional parameter only applicable to \*nix + which indicates that the entire list of config dirs should be + returned. By default, the first item from ``XDG_CONFIG_DIRS `` is + returned, or '/etc/xdg/$appname', if ``XDG_CONFIG_DIRS`` is not set Typical site config directories are: - Mac OS X: same as site_data_dir - Unix: /etc/xdg/ or $XDG_CONFIG_DIRS[i]/ for each value in - $XDG_CONFIG_DIRS - Win *: same as site_data_dir - Vista: (Fail! "C:\ProgramData" is a hidden *system* directory on Vista.) - For Unix, this is using the $XDG_CONFIG_DIRS[0] default, if multipath=False + | **macOS**: + | Same as :func:`~.site_data_dir`. + | **Unix / Linux**: + | ``/etc/xdg/$appname`` (or ``$XDG_CONFIG_DIRS[0]/$appname``) + | **Win Vista**: + | Fails, ``C:\ProgramData`` is a hidden *system* directory + | **Win 7 and above**: + | Same as :func:`~.site_data_dir`. + + For Unix, the first directory in ``$XDG_CONFIG_DIRS`` is used, if + ``multipath=False``. WARNING: Do not use this on Windows. See the Vista-Fail note above for why. """ return _site_config_dir_impl(appname=appname, appauthor=appauthor, version=version, multipath=multipath) -def user_cache_dir(appname=None, appauthor=None, version=None, opinion=True): +def user_cache_dir(appname: str = None, appauthor: str = None, version: str = None, opinion: bool = True): r"""Return full path to the user-specific cache dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "opinion" (boolean) can be False to disable the appending of - "Cache" to the base app data dir for Windows. See - discussion below. + :param appname: The name of application. + If None, just the system directory is returned. + :param appauthor: (only used on Windows) The name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass False to disable it. + :param version: An optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ".". + Only applied when appname is present. + :param opinion: (boolean) If ``False``, disable the appending of + "Cache" to the base app data dir for Windows. See comments below. Typical user cache directories are: - Mac OS X: ~/Library/Caches/ - Unix: ~/.cache/ (XDG default) - Win XP: C:\Documents and Settings\\Local Settings\Application Data\\\Cache - Vista: C:\Users\\AppData\Local\\\Cache + + | **macOS**: + | ``~/Library/Caches/$appname`` + | **Unix / Linux**: + | ``~/.cache/$appname`` (or ``~/$XDG_CACHE_HOME/$appname``) + | **Win XP**: + | ``%USERPROFILE%\Local Settings\Application Data\$appauthor\$appname\Cache`` + | **Win XP and above**: + | ``%USERPROFILE%\AppData\Local\$appauthor\$appname\Cache`` On Windows the only suggestion in the MSDN docs is that local settings go in - the `CSIDL_LOCAL_APPDATA` directory. This is identical to the non-roaming - app data dir (the default returned by `user_data_dir` above). Apps typically - put cache data somewhere *under* the given dir here. Some examples: + the ``CSIDL_LOCAL_APPDATA`` directory. This is identical to the non-roaming + app data dir (the default returned by ``user_data_dir`` above). Apps typically + put cache data somewhere *under* the given dir here. For example:: + ...\Mozilla\Firefox\Profiles\\Cache ...\Acme\SuperApp\Cache\1.0 - OPINION: This function appends "Cache" to the `CSIDL_LOCAL_APPDATA` value. - This can be disabled with the `opinion=False` option. + + OPINION: This function appends "Cache" to the ``CSIDL_LOCAL_APPDATA`` value. + This can be disabled with the ``opinion=False`` option. """ return _user_cache_dir_impl(appname=appname, appauthor=appauthor, version=version, opinion=opinion) -def user_state_dir(appname=None, appauthor=None, version=None, roaming=False): +def user_state_dir(appname: str = None, appauthor: str = None, version: str = None, roaming: bool = False): r"""Return full path to the user-specific state dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "roaming" (boolean, default False) can be set True to use the Windows - roaming appdata directory. That means that for users on a Windows - network setup for roaming profiles, this user data will be - sync'd on login. See - - for a discussion of issues. + :param appname: The name of application. + If None, just the system directory is returned. + :param appauthor: (only used on Windows) The name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass False to disable it. + :param version: An optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ".". + Only applied when appname is present. + :param roaming: Whether to use the roaming appdata directory on Windows. That means + that for users on a Windows network setup for roaming profiles, this user data + will be sync'd on login. See + http://technet.microsoft.com/en-us/library/cc766489(WS.10).aspx for a discussion + of issues. Typical user state directories are: - Mac OS X: same as user_data_dir - Unix: ~/.local/state/ # or in $XDG_STATE_HOME, if defined - Win *: same as user_data_dir - For Unix, we follow this Debian proposal - to extend the XDG spec and support $XDG_STATE_HOME. + | **macOS**: + | Same as :func:`~.user_data_dir`. + | **Unix / Linux**: + | ``~/.local/state/$appname`` (or ``$XDG_STATE_HOME/$appname``) + | **Windows**: + | Same as :func:`~.user_data_dir`. - That means, by default "~/.local/state/". + For Unix, we follow the XDG basedir spec and use ``$XDG_STATE_HOME``. """ return _user_state_dir_impl(appname=appname, appauthor=appauthor, version=version, roaming=roaming) -def user_log_dir(appname=None, appauthor=None, version=None, opinion=True): +def user_log_dir(appname: str = None, appauthor: str = None, version: str = None, opinion: bool = True): r"""Return full path to the user-specific log dir for this application. - "appname" is the name of application. - If None, just the system directory is returned. - "appauthor" (only used on Windows) is the name of the - appauthor or distributing body for this application. Typically - it is the owning company name. This falls back to appname. You may - pass False to disable it. - "version" is an optional version path element to append to the - path. You might want to use this if you want multiple versions - of your app to be able to run independently. If used, this - would typically be ".". - Only applied when appname is present. - "opinion" (boolean) can be False to disable the appending of - "Logs" to the base app data dir for Windows, and "log" to the - base cache dir for Unix. See discussion below. + :param appname: is the name of application. + If None, just the system directory is returned. + :param appauthor: (only used on Windows) is the name of the + appauthor or distributing body for this application. Typically + it is the owning company name. This falls back to appname. You may + pass False to disable it. + :param version: is an optional version path element to append to the + path. You might want to use this if you want multiple versions + of your app to be able to run independently. If used, this + would typically be ".". + Only applied when appname is present. + :param opinion: (boolean) can be False to disable the appending of + "Logs" to the base app data dir for Windows, and "log" to the + base cache dir for Unix. See discussion below. Typical user log directories are: - Mac OS X: ~/Library/Logs/ - Unix: ~/.cache//log # or under $XDG_CACHE_HOME if defined - Win XP: C:\Documents and Settings\\Local Settings\Application Data\\\Logs - Vista: C:\Users\\AppData\Local\\\Logs + + | **macOS**: + | ``~/Library/Logs/$appname`` + | **Unix / Linux**: + | ``~/.cache/$appname/log`` (or ``$XDG_CACHE_HOME/$appname/log``) + | **Win XP**: + | ``%USERPROFILE%\Local Settings\Application Data\$appauthor\$appname\Logs`` + | **Windows Vista or later**: + | ``%USERPROFILE%\AppData\Local\$appauthor\$appname\Logs`` On Windows the only suggestion in the MSDN docs is that local settings go in the `CSIDL_LOCAL_APPDATA` directory. (Note: I'm interested in examples of what some windows apps use for a logs dir.) - OPINION: This function appends "Logs" to the `CSIDL_LOCAL_APPDATA` - value for Windows and appends "log" to the user cache dir for Unix. + OPINION: This function appends ``Logs`` to the ``CSIDL_LOCAL_APPDATA`` + value for Windows and appends ``log`` to the user cache dir for Unix. This can be disabled with the `opinion=False` option. """ return _user_log_dir_impl(appname=appname, appauthor=appauthor, version=version, opinion=opinion) diff --git a/tox.ini b/tox.ini index 248457c7..ba626526 100644 --- a/tox.ini +++ b/tox.ini @@ -65,5 +65,13 @@ commands = python -m pip list --format=columns python -c 'import sys; print(sys.executable)' +[testenv:docs] +extras = + docs +commands = + python -c 'import glob; import subprocess; subprocess.call(["proselint"] + glob.glob("docs/*.rst"))' + sphinx-build -d "{envtmpdir}/doctree" docs "{toxworkdir}/docs_out" --color -b html {posargs} + python -c 'import pathlib; print("documentation available under \{0\}".format((pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html").as_uri()))' + [pytest] junit_family = xunit2