Metadata-Version: 2.0
Name: mike
Version: 0.2.0
Summary: Manage multiple versions of your MkDocs-powered documentation
Home-page: https://github.com/jimporter/mike
Author: Jim Porter
Author-email: porterj@alum.rit.edu
License: BSD
Description-Content-Type: UNKNOWN
Keywords: mkdocs multiple versions
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Documentation
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Requires-Dist: mkdocs (>=0.17.0)
Requires-Dist: jinja2
Requires-Dist: packaging
Requires-Dist: ruamel.yaml (<0.15)
Requires-Dist: six
Provides-Extra: dev
Requires-Dist: coverage; extra == 'dev'
Requires-Dist: flake8 (>=3.0); extra == 'dev'
Requires-Dist: mock; extra == 'dev'
Requires-Dist: pypandoc; extra == 'dev'
Provides-Extra: test
Requires-Dist: coverage; extra == 'test'
Requires-Dist: flake8 (>=3.0); extra == 'test'
Requires-Dist: mock; extra == 'test'

mike
====

**mike** is a Python utility to easily deploy multiple versions of your
`MkDocs <http://www.mkdocs.org>`__-powered docs to a Git branch,
suitable for deploying to Github via ``gh-pages``.

Installation
------------

Like most Python projects, mike uses
`setuptools <https://pythonhosted.org/setuptools/>`__, so installation
is what you might expect:

.. code:: sh

    pip install mike

Usage
-----

Building Your Docs
~~~~~~~~~~~~~~~~~~

Before your first build, you'll probably want to add the version
selector to your MkDocs config. Simply run the following command in the
directory with your ``mkdocs.yml`` file to install the extra CSS and JS
files to your docs:

.. code:: sh

    mike install-extras

mike is designed to produce one version of your docs at a time. That
way, you can easily deploy a new version without touching any older
versions of your docs; this can be especially important if your old docs
are no longer buildable with the newest version of MkDocs (or if they
weren't built with MkDocs at all!). To deploy the current version of
your docs, simply run:

.. code:: sh

    mike deploy [version]

Where ``[version]`` is the current version of your project, represented
however you like (I recommend using ``[major].[minor]`` and excluding
the patch number). You can also pass aliases to the ``deploy`` command
to host a particularly-relevant version of your docs somewhere special
(e.g. ``latest``):

.. code:: sh

    mike deploy [version] [alias]...

If you'd like to specify a title for this version that doesn't match the
version string, you can pass ``-t TITLE``/``--title=TITLE`` as well.

Finally, to push your docs to a remote branch, simply add
``-p``/``--push`` to your command. (Note: this will likely become the
default eventually.)

Viewing Your Docs
~~~~~~~~~~~~~~~~~

To test that your docs have been built as expected, you can serve them
locally from a dev server:

.. code:: sh

    mike serve

By default, this serves the docs on ``http://localhost:8000``, but you
can change this with ``-a``/``--dev-addr``.

Deleting Docs
~~~~~~~~~~~~~

Sometimes you need to delete an old version of your docs, either because
you made a mistake or you're pruning unsupported versions. You can do
this via the ``delete`` subcommand:

.. code:: sh

    mike delete [version-or-alias]...

If you'd like to completely wipe the contents of your docs branch, just
run ``mike delete --all``. Like ``deploy`` above, you can specify
``-p``/``--push`` to push this commit as well.

Listing Docs
~~~~~~~~~~~~

If you ever need to see the list of all currently-deployed doc versions,
you can run:

.. code:: sh

    mike list

Setting the Default Version
~~~~~~~~~~~~~~~~~~~~~~~~~~~

With all the versions of docs you have, you may want to set a *default*
version so that people going to the root of your site are redirected to
the latest version of the docs:

.. code:: sh

    mike set-default [version-or-alias]

Like ``deploy`` and ``delete`` above, you can specify ``-p``/``--push``
to\` push this commit as well.

Renaming a Version
~~~~~~~~~~~~~~~~~~

As you update your docs, you may want to rename the title of a
particular version. For example, your ``1.0`` docs might have the title
``1.0.0``, and when you release a new patch, you want to update the
title to ``1.0.1``. You can do this with the rename command:

.. code:: sh

    mike rename [version-or-alias] [title]

More Details
~~~~~~~~~~~~

For more details on the available options (e.g. specifying which branch
to push to), consult the ``--help`` command for mike.

For Theme Authors
-----------------

If you'd like to provide support for mike in your theme, you just need
to fetch ``versions.json`` and build a version selector.
``versions.json`` looks like this:

.. code:: js

    [
      {"version": "1.0", "title": "1.0.1", "aliases": ["latest"]},
      {"version": "0.9", "title": "0.9", "aliases": []}
    ]

To see an example of how to work with this, check the
```mike/themes/mkdocs`` <mike/themes/mkdocs>`__ directory.

License
-------

This project is licensed under the `BSD 3-clause license <LICENSE>`__.


