Merge 9e492eb into 5bb73f2

README.rst

@@ -1,5 +1,5 @@
-nocasedict - A case-insensitive dictionary for Python
-===============================
+nocasedict - A case-insensitive ordered dictionary for Python
+=============================================================
 
 .. image:: https://badge.fury.io/py/nocasedict.svg
     :target: https://pypi.python.org/pypi/nocasedict/
@@ -9,10 +9,7 @@ nocasedict - A case-insensitive dictionary for Python
     :target: https://travis-ci.org/github/pywbem/nocasedict/builds
     :alt: Travis test status (master)
 
-.. # Update the URL in the Appveyor image link below to match the
-.. # "SVG branchimage URL" from the "master branch status badge" section on
-.. # the Settings -> Badges page of the project on Appveyor.
-.. image:: https://ci.appveyor.com/api/projects/status/UPDATE-THIS/branch/master?svg=true
+.. image:: https://ci.appveyor.com/api/projects/status/d13osi3pxfduj4ap/branch/master?svg=true
     :target: https://ci.appveyor.com/project/andy-maier/nocasedict/history
     :alt: Appveyor test status (master)
 
@@ -28,59 +25,64 @@ nocasedict - A case-insensitive dictionary for Python
 Overview
 --------
 
-TBD
+Class ``NocaseDict`` is a case-insensitive ordered dictionary that preserves
+the lexical case of its keys.
+
+Example:
+
+.. code-block:: bash
+
+    $ python
+    >>> from nocasedict import NocaseDict
+
+    >>> dict1 = NocaseDict({'Alpha': 1, 'Beta': 2})
+
+    >>> dict1['ALPHA']  # Any lookup or comparison by key is case-insensitive
+    1
+
+    >>> print(dict1)  # Any access of keys is case-preserving
+    NocaseDict({'Alpha': 1, 'Beta': 2})
+
 
 Installation
 ------------
 
-To install the latest released version of the nocasedict
-package into your active Python environment:
+To install the latest released version of the nocasedict package into your
+active Python environment:
 
 .. code-block:: bash
 
     $ pip install nocasedict
 
 This will also install any prerequisite Python packages.
 
-For more details and alternative ways to install, see
-`Installation`_.
+For more details and alternative ways to install, see `Installation`_.
 
 .. _Installation: https://nocasedict.readthedocs.io/en/stable/intro.html#installation
 
+
 Documentation
 -------------
 
-* `Documentation for latest released version <https://nocasedict.readthedocs.io/en/stable/>`_
+* `Documentation <https://nocasedict.readthedocs.io/en/stable/>`_
+
 
 Change History
 --------------
 
-* `Change history for latest released version <https://nocasedict.readthedocs.io/en/stable/changes.html>`_
-
-Quick Start
------------
-
-The following simple example script lists the namespaces and the Interop
-namespace in a particular WBEM server:
-
-.. code-block:: python
-
-    #!/usr/bin/env python
-
-    import nocasedict
+* `Change history <https://nocasedict.readthedocs.io/en/stable/changes.html>`_
 
-    ... (tbd) ...
 
 Contributing
 ------------
 
-For information on how to contribute to the
-nocasedict project, see
+For information on how to contribute to the nocasedict project, see
 `Contributing <https://nocasedict.readthedocs.io/en/stable/development.html#contributing>`_.
 
 
 License
 -------
 
 The nocasedict project is provided under the
-`GNU General Public License v3 <https://raw.githubusercontent.com/pywbem/nocasedict/master/LICENSE>`_.
+`GNU Lesser General Public License (LGPL) version 2.1 <https://raw.githubusercontent.com/pywbem/nocasedict/master/LICENSE>`_,
+or (at your option) any later version.

dev-requirements.txt

@@ -47,6 +47,7 @@ sphinxcontrib-websupport>=1.1.2
 Pygments>=2.1.3; python_version == '2.7'
 Pygments>=2.1.3,<2.4.0; python_version == '3.4'
 Pygments>=2.1.3; python_version >= '3.5'
+python-docs-theme>=2020.1
 
 # PyLint (no imports, invoked via pylint script)
 # Pylint requires astroid

docs/appendix.rst

@@ -8,70 +8,13 @@ This section contains information that is referenced from other sections,
 and that does not really need to be read in sequence.
 
 
-.. _`Troubleshooting`:
-
-Troubleshooting
----------------
-
-Here are some trouble shooting hints for ...
-
-
-.. _'Glossary`:
-
-Glossary
---------
-
-.. glossary::
-
-    string
-       a :term:`unicode string` or a :term:`byte string`
-
-    unicode string
-       a Unicode string type (:func:`unicode <py2:unicode>` in
-       Python 2, and :class:`py3:str` in Python 3)
-
-    byte string
-       a byte string type (:class:`py2:str` in Python 2, and
-       :class:`py3:bytes` in Python 3). Unless otherwise
-       indicated, byte strings in this project are always UTF-8 encoded.
-
-    number
-       one of the number types :class:`py:int`, :class:`py2:long` (Python 2
-       only), or :class:`py:float`.
-
-    integer
-       one of the integer types :class:`py:int` or :class:`py2:long` (Python 2
-       only).
-
-    callable
-       a callable object; for example a function, a class (calling it returns a
-       new object of the class), or an object with a :meth:`~py:object.__call__`
-       method.
-
-    hashable
-       a hashable object. Hashability requires an object not only to be able to
-       produce a hash value with the :func:`py:hash` function, but in addition
-       that objects that are equal (as per the ``==`` operator) produce equal
-       hash values, and that the produced hash value remains unchanged across
-       the lifetime of the object. See `term "hashable"
-       <https://docs.python.org/3/glossary.html#term-hashable>`_
-       in the Python glossary, although the definition there is not very crisp.
-       A more exhaustive discussion of these requirements is in
-       `"What happens when you mess with hashing in Python"
-       <https://www.asmeurer.com/blog/posts/what-happens-when-you-mess-with-hashing-in-python/>`_
-       by Aaron Meurer.
-
-
 .. _`References`:
 
 References
 ----------
 
 .. glossary::
 
-   XYZ
-      `XYZ, Version 2.8 <https://xyz.org>`_
-
    Python Glossary
       * `Python 2.7 Glossary <https://docs.python.org/2.7/glossary.html>`_
       * `Python 3.4 Glossary <https://docs.python.org/3.4/glossary.html>`_

docs/changes.rst

@@ -5,8 +5,8 @@ Change log
 ==========
 
 
-nocasedict 0.1.0
--------------------------------------
+nocasedict 1.0.0.dev1
+---------------------
 
 Released: not yet
 

docs/conf.py

@@ -70,6 +70,7 @@ def get_version(version_file):
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',   # disabed, raises anexception
     'sphinx.ext.ifconfig',
+    'python_docs_theme',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -96,7 +97,7 @@ def get_version(version_file):
 author = u"Andreas Maier"
 
 # The short description of the package.
-_short_description = u"A case-insensitive dictionary for Python"
+_short_description = u"A case-insensitive ordered dictionary for Python"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -116,6 +117,9 @@ def get_version(version_file):
 # Usually you set "language" from the command line for these cases.
 language = None
 
+# By default, highlight as Python 3.
+highlight_language = 'python3'
+
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
@@ -210,13 +214,15 @@ def get_version(version_file):
 
 # The theme to use for HTML and HTML Help pages.
 # See https://www.sphinx-doc.org/en/stable/theming.html for built-in themes.
-html_theme = "classic"
+html_theme = 'python_docs_theme'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.
 # See https://www.sphinx-doc.org/en/stable/theming.html for the options
 # available for built-in themes.
 html_theme_options = {
+    'collapsiblesidebar': True,
+    'issues_url': 'https://github.com/pywbem/nocasedict/issues',
 }
 
 # Add any paths that contain custom themes here, relative to this directory.
@@ -241,7 +247,7 @@ def get_version(version_file):
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
@@ -257,7 +263,14 @@ def get_version(version_file):
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
-#html_sidebars = {}
+html_sidebars = {
+    '**': [
+        'localtoc.html',
+        'globaltoc.html',
+        'relations.html',
+        'sourcelink.html',
+    ]
+}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
@@ -279,7 +292,7 @@ def get_version(version_file):
 #html_show_sphinx = True
 
 # If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = False
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
@@ -417,7 +430,7 @@ def get_version(version_file):
 # Selects if automatically documented members are sorted alphabetically
 # (value 'alphabetical'), by member type (value 'groupwise') or by source
 # order (value 'bysource'). The default is alphabetical.
-autodoc_member_order = "bysource"
+autodoc_member_order = "alphabetical"
 
 # This value is a list of autodoc directive options (flags) that should be
 # automatically applied to all autodoc directives. The supported options
@@ -471,9 +484,9 @@ def get_version(version_file):
 #       to datatypes of function parameters can be controlled.
 #
 intersphinx_mapping = {
-  'py': ('https://docs.python.org/2/', None), # agnostic to Python version
-  'py2': ('https://docs.python.org/2', None), # specific to Python 2
-  'py3': ('https://docs.python.org/3', None), # specific to Python 3
+  'py': ('https://docs.python.org/3', None), # default is Python 3
+  'py2': ('https://docs.python.org/2', None),
+  'py3': ('https://docs.python.org/3', None),
 }
 
 intersphinx_cache_limit = 5

docs/index.rst

@@ -1,16 +1,15 @@
 
-nocasedict - A case-insensitive dictionary for Python
-********************************************************************************
+nocasedict - A case-insensitive ordered dictionary for Python
+*************************************************************
 
-TBD
-
-The general project web site is: https://github.com/pywbem/nocasedict
+The project web site is: https://github.com/pywbem/nocasedict
 
 .. toctree::
    :maxdepth: 2
    :numbered:
 
    intro.rst
+   reference.rst
    development.rst
    appendix.rst
    changes.rst

docs/intro.rst

@@ -4,32 +4,43 @@
 Introduction
 ============
 
-.. contents:: Chapter Contents
-   :depth: 2
-
 
 .. _`Functionality`:
 
 Functionality
 -------------
 
-TBD
+Class :class:`nocasedict.NocaseDict` is a case-insensitive ordered dictionary
+that preserves the lexical case of its keys.
+
+Example:
+
+.. code-block:: bash
+
+    $ python
+    >>> from nocasedict import NocaseDict
+
+    >>> dict1 = NocaseDict({'Alpha': 1, 'Beta': 2})
+
+    >>> dict1['ALPHA']  # Any lookup or comparison by key is case-insensitive
+    1
+
+    >>> print(dict1)  # Any access of keys is case-preserving
+    NocaseDict({'Alpha': 1, 'Beta': 2})
 
 
 .. _`Installation`:
 
 Installation
 ------------
 
-TBD
-
 
 .. _`Supported environments`:
 
 Supported environments
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Pywbem is supported in these environments:
+The package is supported in these environments:
 
 * Operating Systems: Linux, Windows (native, and with UNIX-like environments),
   OS-X
@@ -108,9 +119,6 @@ it to):
     $ python -c "import nocasedict; print('ok')"
     ok
 
-In case of trouble with the installation, see the :ref:`Troubleshooting`
-section.
-
 
 .. _`Package version`:
 
@@ -201,9 +209,6 @@ the nocasedict project, by version type:
 Python namespaces
 -----------------
 
-TBD - describe the python namespaces to clarify what is for external use
-and what is internal.
-
 This documentation describes only the external APIs of the
 nocasedict project, and omits any internal symbols and
 any sub-modules.