Metadata-Version: 2.0
Name: mike
Version: 0.3.2
Summary: Manage multiple versions of your MkDocs-powered documentation
Home-page: https://github.com/jimporter/mike
Author: Jim Porter
Author-email: itsjimporter@gmail.com
License: BSD
Description-Content-Type: UNKNOWN
Keywords: mkdocs multiple versions
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
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
Classifier: Programming Language :: Python :: 3.6
Requires-Dist: mkdocs (>=0.17.0)
Requires-Dist: jinja2
Requires-Dist: packaging
Requires-Dist: ruamel.yaml (<0.15)
Requires-Dist: six
Requires-Dist: enum34
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``.

Why Use mike?
-------------

mike is built around the idea that once you've generated your docs for a
particular version, you should never need to touch that version again.
This means you never have to worry about breaking changes in MkDocs,
since your old docs (built with an old version of MkDocs) are already
generated and sitting in your ``gh-pages`` branch.

While mike is flexible, it's optimized around putting your docs in a
``<major>.<minor>`` directory, with optional aliases (e.g. ``latest`` or
``dev``) to particularly notable versions. This makes it easy to make
permalinks to whatever version of the documentation you want to direct
people to.

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. If
``version`` already exists, this command will *also* update all of the
pre-existing aliases for it.

Finally, to push your docs to a remote branch, simply add
``-p``/``--push`` to your command.

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 ``version-or-alias`` is a version, this will delete the version and
all its aliases from the branch; if it's an alias, it will only delete
that 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.

Changing a Version's Title
~~~~~~~~~~~~~~~~~~~~~~~~~~

As you update your docs, you may want to change 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 ``retitle`` command:

.. code:: sh

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

As with other commands that change your docs, you can specify
``-p``/``--push`` to push this commit.

Adding a New Version Alias
~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes, you might need to add a new alias for a version without
rebuilding your documentation. You can use the ``alias`` command for
this:

.. code:: sh

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

Once again, you can specify ``-p``/``--push`` to push this commit.

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

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

Staying in Sync
---------------

mike will do its best to stay in-sync with your remote repository and
will automatically update your local branch to match the remote's if
possible (note that mike *won't* automatically ``git fetch`` anything).
If your local branch has diverged from your remote, mike will leave it
as-is and ask you what to do. To ignore the remote's state, just pass
``--ignore``; to update to the remote's state, pass ``--rebase``.

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>`__.


