Better docs and API layout

CONTRIBUTING.rst

@@ -109,5 +109,3 @@ Before you submit a pull request, check that it meets these guidelines:
 3. The pull request should work for Python 2.7 and up. Check
    https://travis-ci.org/cblegare/xdmenu/pull_requests
    and make sure that the tests pass for all supported Python versions.
-
-Thanks :)

LICENSE

@@ -1,19 +1,19 @@
-GNU GENERAL PUBLIC LICENSE
+GNU LESSER GENERAL PUBLIC LICENSE
 
                       Version 3, 29 June 2007
 
-    Yet an other wrapper for dmenu
+    xdmenu
     Copyright (C) 2017  Charles Bouchard-Légaré
 
-    This program is free software: you can redistribute it and/or modify
-    it under the terms of the GNU General Public License as published by
+    xdmenu is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Lesser General Public License as published by
     the Free Software Foundation, either version 3 of the License, or
     (at your option) any later version.
 
-    This program is distributed in the hope that it will be useful,
+    xdmenu is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-    GNU General Public License for more details.
+    GNU Lesser General Public License for more details.
 
-    You should have received a copy of the GNU General Public License
-    along with this program.  If not, see <http://www.gnu.org/licenses/>.
+    You should have received a copy of the GNU Lesser General Public License
+    along with xdmenu.  If not, see <http://www.gnu.org/licenses/>.

README.rst

@@ -19,15 +19,16 @@ Extensible wrapper for dmenu_.
     `dmenu is a dynamic menu for X, originally designed for dwm. It manages
     large numbers of user-defined menu items efficiently.`
 
-`xdmenu` is free software and licensed under the GNU General Public License v3.
-See :ref:`license` for details.
+`xdmenu` is free software and licensed under the GNU Lesser General Public
+License v3. See :ref:`license` for details.
 
 
 Features
 --------
 
 * Many options available in patches built in
 * Additional options can be added
+* Easy to extend for other tools such as `Rofi`_
 
 
 Credits
@@ -39,3 +40,4 @@ project template.
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _`cblegare/pythontemplate`: https://github.com/cblegare/pythontemplate
 .. _dmenu: http://tools.suckless.org/dmenu/
+.. _Rofi: https://davedavenport.github.io/rofi/

docs/conf.py

@@ -73,6 +73,11 @@ def string_to_version(vstring):
 ]
 
 
+# Mappings to external docs
+intersphinx_mapping = {'python': ('https://docs.python.org/3.4',
+                                  None)}
+
+
 # We enable the nitpicky mode that will warn about all references where the
 # target cannot be found.
 # Some python built-ins can not be found (including 'type' and 'object').
@@ -105,6 +110,7 @@ def string_to_version(vstring):
     ('py:obj', 'str'),
     ('py:obj', 'int'),
     ('py:obj', 'bool'),
+    ('py:obj', 'float'),
     ('py:obj', ''),
     # Specific warnings
     ('py:class', 'classmethod'),
@@ -114,6 +120,7 @@ def string_to_version(vstring):
     ('py:func', 'setuptools.setup'),
     ('py:class', 'subprocess.Popen'),
     ('py:class', 'exceptions.Exception'),
+    ('py:class', 'Exception'),
 
 ]
 

docs/contributing.rst

@@ -1 +1,5 @@
 .. include:: ../CONTRIBUTING.rst
+
+Also, have a look at the full-fledged :ref:`setup`!
+
+Thanks :)

docs/index.rst

@@ -39,7 +39,6 @@ Development resources
    modules
 
 
-
 Indices and tables
 ==================
 

docs/modules.rst

@@ -1,8 +1,7 @@
-xdmenu
-======
+API documentation
+=================
 
 .. toctree::
    :maxdepth: 4
 
-   tests
    xdmenu

docs/setup_script.rst

@@ -1,7 +1,7 @@
 .. _setup:
 
 
-setup module
+Setup Script
 ============
 
 

docs/testing.rst

@@ -67,3 +67,12 @@ that this specific bug will not occur again. The full name is *non-regression
 test*. It can also be a test made prior to changing an application to make
 sure the application provides the same outcome. Put these in the
 :mod:`tests.regression` package.
+
+
+All Automated tests
+===================
+
+.. toctree::
+   :maxdepth: 4
+
+   tests

docs/usage.rst

@@ -15,21 +15,21 @@ behavior of `dmenu`.
 .. autoclass:: xdmenu.Dmenu
     :noindex:
 
-Run `dmenu` using :meth:`xdmenu.Dmenu.run`.
+Run `dmenu` using :meth:`xdmenu.BaseMenu.run` which all child class should have.
 
-.. automethod:: xdmenu.Dmenu.run
+.. automethod:: xdmenu.BaseMenu.run
     :noindex:
 
 If you only want to get the command line arguments, simply use
-:meth:`xdmenu.Dmenu.make_cmd`
+:meth:`xdmenu.BaseMenu.make_cmd`
 
-.. automethod:: xdmenu.Dmenu.make_cmd
+.. automethod:: xdmenu.BaseMenu.make_cmd
     :noindex:
 
 Since `xdmenu` is intended to be extensible, you can add supported options
-using :meth:`xdmenu.Dmenu.add_arg`
+using :meth:`xdmenu.BaseMenu.add_arg`
 
-.. automethod:: xdmenu.Dmenu.add_arg
+.. automethod:: xdmenu.BaseMenu.add_arg
     :noindex:
 
 

requirements.txt

@@ -1,14 +1,11 @@
+flake8
 flake8-quotes>=0.3
-radon
+xenon
 sphinx_rtd_theme
-pycodestyle>=2.2
-pytest
+sphinx>=1.5
 pytest-cov
-pytest-flake8
-flake8
-coverage
 click
-sphinx>=1.5
-sphinx-autodoc-typehints
-xenon
-pytest-cookies
+pytest
+coverage
+pycodestyle>=2.2
+pytest-flake8

setup.cfg

@@ -4,6 +4,9 @@ lint=flake8
 
 [tool:pytest]
 addopts =
+    --cov-report term
+    --cov-report html:build/reports/coverage_html
+    --cov-report xml:build/reports/coverage.xml
     --cov=xdmenu
     --verbose
     --flake8
@@ -26,22 +29,17 @@ exclude =
     # This contains distribution that we don't want to check
     dist,
     # The command line entry point script is expected to fail some checks
-    __main__.py,
-    # The root __init__ is expected to fail some checks
-    xdmenu/__init__.py
+    __main__.py
 show-source = True
 doctests = True
 
 [isort]
 from_first = 1
 known_standard_library = setuptools
-known_third_party =
-    flask_ripozo,
-    ripozo
 known_first_party = ""
 
 [sdist]
 formats=gztar,zip
 
 [bdist_wheel]
-python-tag=py35
+python-tag=py2.py3-none-any

setup.py

@@ -20,7 +20,6 @@
 except ImportError:
     # python 2
     from urlparse import urlparse
-import six
 
 
 __all__ = (
@@ -285,9 +284,25 @@ def setup_requires(self):
         Returns:
              List[str]: A list of short strings
         """
-        return ['sphinx>=1.5',
-                'sphinx-autodoc-typehints',
-                'sphinx_rtd_theme']
+        return []
+
+    @property
+    def extras_require(self):
+        """
+        A dictionary mapping names of `extras` (optional features of your
+        project) to strings or lists of strings specifying what other
+        distributions must be installed to support those features.
+
+        See Also:
+            http://setuptools.readthedocs.io/en/latest/setuptools.html#declaring-extras-optional-features-with-their-own-dependencies
+
+        Returns:
+            Dict: Lists of dependencies indexed by the feature they enable.
+        """
+        develop = ['sphinx>=1.5',
+                   'sphinx_rtd_theme']
+        return {'develop': develop,
+                'all': develop}
 
     def setup(self):
         """Run :func:`setuptools.setup` using :func:~`raw`."""
@@ -325,7 +340,8 @@ def raw(self):
                               'mk_req': Requirements},
                     install_requires=self.install_requires,
                     tests_require=self.tests_require,
-                    setup_requires=self.setup_requires)
+                    setup_requires=self.setup_requires,
+                    extras_require = self.extras_require)
 
     def __str__(self):
         """Provide a human-readable representation."""
@@ -334,25 +350,25 @@ def __str__(self):
 
     @staticmethod
     def _ensure_short_string(string):
-        string = six.u(string)
+        string = str(string)
         assert len(string) <= 200
         return string
 
     @staticmethod
     def _ensure_long_string(string):
-        string = six.u(string)
+        string = str(string)
         return string
 
     @staticmethod
     def _ensure_email_address(string):
-        string = six.u(string)
+        string = str(string)
         _, email_str = email.utils.parseaddr(str(string))
         assert email_str == str(string)
         return string
 
     @staticmethod
     def _ensure_url(string, qualifying=None):
-        string = six.u(string)
+        string = str(string)
         min_attributes = ('scheme', 'netloc')
 
         qualifying = min_attributes if qualifying is None else qualifying
@@ -414,11 +430,15 @@ def run(self):
         dependencies.extend(metadata.install_requires)
         dependencies.extend(metadata.tests_require)
 
+        for key in metadata.extras_require:
+            dependencies.extend(metadata.extras_require[key])
+
         requirements_filepath = os.path.join(PROJECT_ROOT, 'requirements.txt')
 
         with open(requirements_filepath, 'w') as opened:
             opened.write('\n'.join(set(dependencies)))
 
+
 class Documentation(setuptools.Command):
     """
     Make the documentation (without the *Make* program).
@@ -433,15 +453,17 @@ class Documentation(setuptools.Command):
 
     description = 'create documentation distribution'
     user_options = [
-        ('builder=', None, 'documentation output format'
-                           ' [default: html]'),
-        ('dist-dir=', None, 'directory to put final built distributions in'
-                            ' [default: dist/docs]'),
+        ('builder=', None, 'documentation output format '
+                           '[default: html]'),
+        ('dist-dir=', None, 'directory to put final built distributions in '
+                            '[default: dist/docs]'),
         ('build-dir=', None, 'temporary directory for creating the '
-                             'distribution'
-                             ' [default: build/docs]'),
-        ('src-dir=', None, 'documentation source directory'
-                           ' [default: docs]'),
+                             'distribution '
+                             '[default: build/docs]'),
+        ('src-dir=', None, 'documentation source directory '
+                           '[default: docs]'),
+        ('ignore-warnings', None, 'let the documentation be built even if '
+                                  'there are warnings [default: False]')
     ]
 
     targets = {
@@ -469,9 +491,11 @@ def initialize_options(self):
         self.dist_dir = os.path.join(PROJECT_ROOT, 'dist', 'docs')
         self.build_dir = os.path.join(PROJECT_ROOT, 'build', 'docs')
         self.src_dir = os.path.join(PROJECT_ROOT, 'docs')
+        self.ignore_warnings = False
 
     def finalize_options(self):
         """Post-process options."""
+        self.ignore_warnings = bool(self.ignore_warnings)
         if self.builder in self.targets:
             self._actual_targets = [self.builder]
         elif self.builder == 'all':
@@ -548,7 +572,6 @@ def _build_source(self):
         return build_dir
 
     def _build_doc(self, target):
-        from datetime import datetime
         import shutil
         import sphinx
 
@@ -566,14 +589,17 @@ def _build_doc(self, target):
             '-d', cached_directory,  # path for the cached doctree files
             '-n',                    # warn about all missing references
             '-q',                    # no output on stdout, warnings on stderr
-            '-W',                    # turn warnings into errors
             '-T',                    # show full traceback on exception
             '-D', 'project={!s}'.format(metadata.name),
-            '-D', 'version={!s}'.format(metadata.version),
-            rst_src,
-            build_dir
+            '-D', 'version={!s}'.format(metadata.version)
         ]
 
+        if not self.ignore_warnings:
+            all_sphinx_opts.append('-W')
+
+        all_sphinx_opts.append(rst_src)
+        all_sphinx_opts.append(build_dir)
+
         sphinx.build_main([str(arg) for arg in all_sphinx_opts])
         shutil.rmtree(str(dist_dir), ignore_errors=True)
         mkdir_p(os.path.dirname(dist_dir))

tox.ini

@@ -1,8 +1,10 @@
 [tox]
-indexserver =
-    DEV = extra_index_url
+envlist = py27, py33, py34, py35, pypy, pypy3
+
+
 
 [testenv]
 deps =
-    docutils        # comes from standard PyPI
-    :DEV:mypackage  # will be installed from custom "DEV" pypi url
+    -rrequirements.txt
+commands =
+    pytest --basetemp={envtmpdir}