GitHub Pages guide. Fixed logging. Classifiers.

Only test sphinx-build in main Travis tests (script section). Save docsV
for after_success. If a previous branch is broken it shouldn't break the
current branch's tests.

Adding GitHub Pages guide in docs.

Adding classifiers. Getting ready for release.

Moved log statements around. Was printing nothing significant to push
and then pushed successfully. Didn't make sense.

Tox docsV testenv changed from build to push. Not used in Travis yet.

Author: Robpol86

.travis.yml

@@ -8,7 +8,7 @@ install: pip install appveyor-artifacts coveralls tox
 before_script:
   - git config --global user.email "[email protected]"
   - git config --global user.name "Travis CI"
-script: tox -e lint,py35,py34,py33,pypy,py27,docsV
+script: tox -e lint,py35,py34,py33,pypy,py27,docs
 after_success:
   - coveralls
 

docs/github_pages.rst

@@ -0,0 +1,138 @@
+.. _github_pages:
+
+============
+GitHub Pages
+============
+
+It's pretty easy to use `GitHub Pages <https://pages.github.com/>`_ to host all of your versioned documentation. Before
+starting be sure to go through the :ref:`tutorial` first to make sure you can build your docs locally. You'll also want
+to do the :ref:`push-all-versions` section.
+
+.. tip::
+
+    You may want to enable GitHub's `protected branches <https://help.github.com/articles/about-protected-branches/>`_
+    feature for the gh-pages branch to prevent you or anyone from accidentally deleting the branch from remote.
+
+This guide assumes:
+
+1. You already have documentation in your master branch and SCVersioning builds it locally. If not you'll need to use
+   the :option:`--root-ref` argument.
+2. You already have your CI configured and running on your repo (this guide uses Travis CI but it should work on any
+   other).
+
+Turn Off Jekyll
+===============
+
+Building on the steps in the :ref:`tutorial` document you'll want to disable Jekyll because it doesn't copy over files
+and directories `that start with underscores <https://github.com/blog/572-bypassing-jekyll-on-github-pages>`_, which
+Sphinx uses.
+
+.. code-block:: bash
+
+    git checkout gh-pages
+    git pull origin gh-pages
+    touch .nojekyll
+    git add .nojekyll
+    git commit
+    git push origin gh-pages
+    git checkout master  # Or whatever branch you were in.
+
+Then navigate to https://username.github.io/repo_name/ and if you used ``.`` for your :option:`REL_DST` you should see
+your HTML docs there. Otherwise if you used something like ``html/docs`` you'll need to navigate to
+https://username.github.io/repo_name/html/docs/.
+
+.. tip::
+
+    Old repositories may not have **Enforce HTTPS** enabled for their GitHub Pages. It's a good idea to enable this
+    feature. More info: https://help.github.com/articles/securing-your-github-pages-site-with-https/
+
+Running in CI
+=============
+
+The goal of using GitHub Pages is to have docs automatically update on every new/changed branch/tag. In this example
+we'll be using Travis CI but any CI should work.
+
+Travis won't be able to push any changes to the gh-pages branch without SSH keys. This guide will worry about just
+getting Travis to run SCVersioning. It should only fail when trying to push to origin.
+
+CI Config File
+--------------
+
+Edit your CI configuration file (e.g. `.travis.yml <https://docs.travis-ci.com/user/customizing-the-build/>`_) with:
+
+.. code-block:: yaml
+
+    install:
+      - pip install sphinxcontrib-versioning
+    after_success:
+      - git config --global user.email "[email protected]"
+      - git config --global user.name "Travis CI"
+      - sphinx-versioning push gh-pages . docs
+
+The two git config lines are needed to make commits locally to the gh-pages branch (cloned to a temporary directory by
+SCVersioning). If you want SCVersioning to delete unrelated files from the gh-pages branch (e.g. deleted branches' HTML
+documentation, deleted tags, etc) change the sphinx-versioning command to:
+
+.. code-block:: bash
+
+    sphinx-versioning -e .gitignore -e .nojekyll -e README.rst push gh-pages . docs
+
+This tells SCVersioning to delete all files in gh-pages except those three. More information in :option:`--grm-exclude`.
+
+Commit
+------
+
+Commit your changes to the CI config file and push. You should see documentation building successfully, but it should
+fail when it tries to push since we haven't given your CI any permission to make changes to the git repository.
+
+SSH Key
+=======
+
+Now that we know SCVersioning works fine locally and remotely it's time to unleash it. We'll be using
+`Deploy Keys <https://developer.github.com/guides/managing-deploy-keys/>`_ to grant Travis write access to your
+repository. At the time of this writing this is the most narrow-scoped authorization method for docs deployment.
+
+To avoid leaking the SSH private key (thereby granting write access to the repo) we'll be using Travis CI's
+`Encrypting Files <https://docs.travis-ci.com/user/encrypting-files/>`_ feature. You'll need to install the Travis CI
+`ruby client <https://github.com/travis-ci/travis.rb#installation>`_ for this section.
+
+ssh-keygen
+----------
+
+First we'll create the SSH key pair.
+
+.. code-block:: bash
+
+    ssh-keygen -t rsa -b 4096 -C "Travis CI Deploy Key" -N "" -f docs/key
+    cat docs/key.pub  # We'll be adding this to GitHub's repo settings page.
+    travis encrypt-file docs/key docs/key.enc --add after_success  # Updates .travis.yml
+    rm docs/key docs/key.pub  # Don't need these anymore.
+
+We need to give GitHub your SSH **public** key (the one we ran with ``cat``). Go to
+https://github.com/username/repo_name/settings/keys and click "Add deploy key". The title could be anything (e.g.
+"Travis CI Deploy Key"). The key you're pasting will be one long line and will look something like "ssh-rsa AAAAB3N...==
+Travis CI Deploy Key"
+
+Be sure to check **Allow write access**.
+
+travis.yml
+----------
+
+The ``travis encrypt-file`` command should have updated your ``.travis.yml`` with the openssl command for you. However
+we still need to make one more change to the file before committing it. Update .travis.yml with these ``chmod``,
+``eval``, and ``git remote`` commands. The after_success section should end up looking like this:
+
+.. code-block:: bash
+
+    after_success:
+      - touch docs/key; chmod 600 docs/key  # Secure before storing key data.
+      - openssl aes-256-cbc ... -in docs/key.enc -out docs/key -d
+      - eval `ssh-agent -s`; ssh-add docs/key
+      - git config --global user.email "[email protected]"
+      - git config --global user.name "Travis CI"
+      - git remote set-url origin "[email protected]:$TRAVIS_REPO_SLUG"
+      - export ${!TRAVIS*}  # Optional, for commit messages.
+      - sphinx-versioning push gh-pages . docs
+
+Finally commit both **.travis.yml** and the encrypted **docs/key.enc** file. Push and watch Travis update your docs
+automatically for you.

docs/index.rst

@@ -42,6 +42,12 @@ Project Links
     settings
     themes
 
+.. toctree::
+    :maxdepth: 2
+    :caption: Web Hosting
+
+    github_pages
+
 .. toctree::
     :maxdepth: 1
     :caption: Appendix

docs/tutorial.rst

@@ -4,7 +4,7 @@
 Tutorial
 ========
 
-This section will go over the basics of the project.
+This guide will go over the basics of the project.
 
 Make sure that you've already :ref:`installed <install>` it.
 

setup.py

@@ -34,7 +34,21 @@ def readme():
     author='@Robpol86',
     author_email='[email protected]',
     classifiers=[
-        'Private :: Do Not Upload',
+        'Development Status :: 5 - Production/Stable',
+        'Environment :: Console',
+        'Framework :: Sphinx :: Extension',
+        'Intended Audience :: Developers',
+        'License :: OSI Approved :: MIT License',
+        'Operating System :: MacOS',
+        'Operating System :: POSIX :: Linux',
+        'Operating System :: POSIX',
+        'Programming Language :: Python :: 2.7',
+        'Programming Language :: Python :: 3.3',
+        'Programming Language :: Python :: 3.4',
+        'Programming Language :: Python :: 3.5',
+        'Programming Language :: Python :: Implementation :: PyPy',
+        'Topic :: Documentation :: Sphinx',
+        'Topic :: Software Development :: Documentation',
     ],
     description='Sphinx extension that allows building versioned docs for self-hosting.',
     entry_points={'console_scripts': ['sphinx-versioning = sphinxcontrib.versioning.__main__:entry_point']},

sphinxcontrib/versioning/__main__.py

@@ -219,7 +219,6 @@ def main(config):
     for _ in range(PUSH_RETRIES):
         with TempDir() as temp_dir:
             if main_push(config, root, temp_dir):
-                log.info('Successfully pushed to remote repository.')
                 return
         log.warning('Failed to push to remote repository. Retrying in %d seconds...', PUSH_SLEEP)
         time.sleep(PUSH_SLEEP)
@@ -235,6 +234,7 @@ def entry_point():
         config = get_arguments(sys.argv, __doc__)
         setup_logging(verbose=config['--verbose'], colors=not config['--no-colors'])
         main(config)
+        logging.info('Success.')
     except HandledError:
         logging.critical('Failure.')
         sys.exit(1)

sphinxcontrib/versioning/git.py

@@ -404,4 +404,5 @@ def commit_and_push(local_root, versions):
             return False
         raise GitError('Failed to push to remote.', exc.output)
 
+    log.info('Successfully pushed to remote repository.')
     return True

tox.ini

@@ -51,10 +51,11 @@ deps =
 
 [testenv:docsV]
 commands =
-    sphinx-versioning -t -S semver,chrono build docs/_build/html docs -- -W
+    sphinx-versioning -t -S semver,chrono -e .gitignore -e .nojekyll -e README.rst push gh-pages . docs -- -W
 deps =
     {[testenv:docs]deps}
 passenv =
+    HOME
     HOSTNAME
     SSH_AUTH_SOCK
     TRAVIS*