Updated docs, revamped contributing section, added doc linting (arrow…

…-py#647)

* Cleaned up docs and improved contributing section

* Added linting for docs and updated Travis config to use Ubuntu 18

* Cleaned up Makefile; added groovy emoji

* Adjusted emoji

* Removed emoji

* Tweaked wording in features section

* Added emoji in contributing.

* Fix Travis CI Python 3.5 build

* Removed quieting of docs linting output to provide more info

* Added emoji to docs title and minor tweaks to wording

* Capitalize project title

* Re-added make.bat and made project name a unicode string

.travis.yml

@@ -1,20 +1,26 @@
 language: python
-dist: xenial
+dist: bionic
 matrix:
     include:
-        - python: 2.7
+        - name: "Python 2.7"
+          python: "2.7"
           env: TOXENV=py27
-        - python: 3.5
+        - name: "Python 3.5"
+          dist: xenial
+          python: "3.5"
           env: TOXENV=py35
-        - python: 3.6
+        - name: "Python 3.6"
+          python: "3.6"
           env: TOXENV=py36
-        - python: 3.7
+        - name: "Python 3.7"
+          python: "3.7"
           env: TOXENV=py37
-        - python: 3.8-dev
+        - name: "Python 3.8"
+          python: "3.8-dev"
           env: TOXENV=py38
         - name: "Linting"
-          python: 3.7
-          env: TOXENV=lint
+          python: "3.7"
+          env: TOXENV=lint,docs
           cache:
               directories:
                   - $HOME/.cache/pre-commit

Makefile

@@ -17,14 +17,11 @@ test:
 	rm -f .coverage
 	. venv/bin/activate && nosetests
 
-test-dev:
-	rm -f .coverage
-	. venv/bin/activate && python -Wd -m nose
-
 lint:
 	venv/bin/pre-commit run --all-files --show-diff-on-failure
 
 docs:
+	rm -rf docs/_build
 	. venv/bin/activate && cd docs; make html
 
 clean:

README.rst

@@ -25,39 +25,37 @@ Arrow: Better dates & times for Python
 
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
    :alt: Code Style: Black
-   :target: https://github.com/python/black
+   :target: https://github.com/psf/black
 
-What?
------
 
-Arrow is a Python library that offers a sensible, human-friendly approach to creating, manipulating, formatting and converting dates, times, and timestamps.  It implements and updates the datetime type, plugging gaps in functionality, and provides an intelligent module API that supports many common creation scenarios.  Simply put, it helps you work with dates and times with fewer imports and a lot less code.
+**Arrow** is a Python library that offers a sensible and human-friendly approach to creating, manipulating, formatting and converting dates, times and timestamps. It implements and updates the datetime type, plugging gaps in functionality and providing an intelligent module API that supports many common creation scenarios. Simply put, it helps you work with dates and times with fewer imports and a lot less code.
 
-Arrow is heavily inspired by `moment.js <https://github.com/moment/moment>`_ and `requests <https://github.com/psf/requests>`_.
+Arrow is named after the `arrow of time <https://en.wikipedia.org/wiki/Arrow_of_time>`_ and is heavily inspired by `moment.js <https://github.com/moment/moment>`_ and `requests <https://github.com/psf/requests>`_.
 
-Why?
-----
+Why use Arrow over built-in modules?
+------------------------------------
 
-Python's standard library and some other low-level modules have near-complete date, time and timezone functionality but don't work very well from a usability perspective:
+Python's standard library and some other low-level modules have near-complete date, time and timezone functionality, but don't work very well from a usability perspective:
 
-- Too many modules:  datetime, time, calendar, dateutil, pytz and more
-- Too many types:  date, time, datetime, tzinfo, timedelta, relativedelta, etc.
+- Too many modules: datetime, time, calendar, dateutil, pytz and more
+- Too many types: date, time, datetime, tzinfo, timedelta, relativedelta, etc.
 - Timezones and timestamp conversions are verbose and unpleasant
 - Timezone naivety is the norm
-- Gaps in functionality:  ISO-8601 parsing, timespans, humanization
+- Gaps in functionality: ISO-8601 parsing, timespans, humanization
 
 Features
 --------
 
-- Fully implemented, drop-in replacement for datetime
+- Fully-implemented, drop-in replacement for datetime
 - Supports Python 2.7, 3.5, 3.6, 3.7 and 3.8
-- Timezone-aware & UTC by default
+- Timezone-aware and UTC by default
 - Provides super-simple creation options for many common input scenarios
 - :code:`shift` method with support for relative offsets, including weeks
 - Formats and parses strings automatically
-- Partial support for ISO-8601
+- Wide support for ISO-8601
 - Timezone conversion
 - Timestamp available as a property
-- Generates time spans, ranges, floors and ceilings in timeframes from year to microsecond
+- Generates time spans, ranges, floors and ceilings for time frames ranging from microsecond to year
 - Humanizes and supports a growing list of contributed locales
 - Extensible for your own Arrow-derived types
 
@@ -79,6 +77,9 @@ Example Usage
 .. code-block:: python
 
     >>> import arrow
+    >>> arrow.get('2013-05-11T21:23:58.970460+07:00')
+    <Arrow [2013-05-11T21:23:58.970460+07:00]>
+
     >>> utc = arrow.utcnow()
     >>> utc
     <Arrow [2013-05-11T21:23:58.970460+00:00]>
@@ -91,9 +92,6 @@ Example Usage
     >>> local
     <Arrow [2013-05-11T13:23:58.970460-07:00]>
 
-    >>> arrow.get('2013-05-11T21:23:58.970460+00:00')
-    <Arrow [2013-05-11T21:23:58.970460+00:00]>
-
     >>> local.timestamp
     1368303838
 
@@ -119,4 +117,11 @@ For full documentation, please visit `arrow.readthedocs.io <https://arrow.readth
 Contributing
 ------------
 
-Contributions are welcome for both code and localizations. To get started, find an issue or feature to tackle on `the issue tracker <https://github.com/crsmithdev/arrow/issues>`_ and then fork `this repository <https://github.com/crsmithdev/arrow>`_ on GitHub to begin making changes. If you would like to help with localizations, please see `locales.py <https://github.com/crsmithdev/arrow/blob/master/arrow/locales.py>`_ to see what locales are currently supported. If you are helping with code, make sure to add a few tests to ensure that the bug was fixed or the feature works as intended.
+Contributions are welcome for both code and localizations (adding and updating locales). Begin by gaining familiarity with the Arrow library and its features. Then, jump into contributing:
+
+1. Find an issue or feature to tackle on the `issue tracker <https://github.com/crsmithdev/arrow/issues>`_. Issues marked with the `"good first issue" label <https://github.com/crsmithdev/arrow/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22>`_ may be a great place to start!
+2. Fork `this repository <https://github.com/crsmithdev/arrow>`_ on GitHub and begin making changes in a branch.
+3. Add a few tests to ensure that the bug was fixed or the feature works as expected.
+4. Submit a pull request and await feedback 😃.
+
+If you have any questions along the way, feel free to ask them `here <https://github.com/crsmithdev/arrow/issues/new?labels=question>`_.

docs/conf.py

@@ -14,7 +14,7 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "arrow"
+project = u"Arrow 🏹"
 copyright = "2019, Chris Smith"
 author = "Chris Smith"
 
@@ -45,7 +45,7 @@
 html_show_copyright = True
 
 html_theme_options = {
-    "description": "Arrow is a sensible and human-friendly approach to dates, times, and timestamps.",
+    "description": "Arrow is a sensible and human-friendly approach to dates, times and timestamps.",
     "github_user": "crsmithdev",
     "github_repo": "arrow",
     "github_banner": True,

docs/make.bat

@@ -1,35 +1,35 @@
-@ECHO OFF
-
-pushd %~dp0
-
-REM Command file for Sphinx documentation
-
-if "%SPHINXBUILD%" == "" (
-	set SPHINXBUILD=sphinx-build
-)
-set SOURCEDIR=.
-set BUILDDIR=_build
-
-if "%1" == "" goto help
-
-%SPHINXBUILD% >NUL 2>NUL
-if errorlevel 9009 (
-	echo.
-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
-	echo.installed, then set the SPHINXBUILD environment variable to point
-	echo.to the full path of the 'sphinx-build' executable. Alternatively you
-	echo.may add the Sphinx directory to PATH.
-	echo.
-	echo.If you don't have Sphinx installed, grab it from
-	echo.http://sphinx-doc.org/
-	exit /b 1
-)
-
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-goto end
-
-:help
-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-
-:end
-popd
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

requirements.txt

@@ -7,4 +7,4 @@ python-dateutil==2.8.*
 pytz==2019.*
 simplejson==3.16.*
 sphinx==1.8.*; python_version == '2.7'
-sphinx==2.1.*; python_version >= '3.5'
+sphinx==2.2.*; python_version >= '3.5'

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-envlist = py{27,35,36,37,38},lint
+envlist = py{27,35,36,37,38},lint,docs
 skip_missing_interpreters = true
 
 [testenv]
@@ -14,3 +14,16 @@ deps = pre-commit
 commands =
     pre-commit install
     pre-commit run --all-files --show-diff-on-failure
+
+[testenv:docs]
+basepython = python3
+skip_install = true
+changedir = docs
+deps =
+    doc8
+    sphinx
+    python-dateutil
+whitelist_externals = make
+commands =
+    doc8 index.rst ../README.rst --extension .rst --ignore D001
+    make html SPHINXOPTS="-W --keep-going"