[Python-modules-commits] [python-mkdocs] 01/04: Import python-mkdocs_0.14.0.orig.tar.gz
Brian May
bam at moszumanska.debian.org
Tue Oct 20 06:29:13 UTC 2015
This is an automated email from the git hooks/post-receive script.
bam pushed a commit to branch master
in repository python-mkdocs.
commit 3cf05efcd9fcc699d0bdaaf0fa548918c4443b52
Author: Brian May <bam at debian.org>
Date: Tue Oct 20 12:41:11 2015 +1100
Import python-mkdocs_0.14.0.orig.tar.gz
---
.travis.sh | 10 -
.travis.yml | 26 +-
CONTRIBUTING.md | 6 +
README.md | 33 +-
appveyor.yml | 23 +
docs/about/contributing.md | 65 +++
docs/about/license.md | 1 -
docs/about/release-notes.md | 231 +++++++-
docs/css/extra.css | 9 +
docs/img/mkdocs.png | Bin 0 -> 161285 bytes
docs/index.md | 42 +-
docs/user-guide/configuration.md | 213 ++++---
docs/user-guide/deploying-your-docs.md | 132 +++++
docs/user-guide/styling-your-docs.md | 286 +++++++++-
docs/user-guide/writing-your-docs.md | 106 ++--
mkdocs.yml | 17 +-
mkdocs/__init__.py | 2 +-
mkdocs/assets/search/mkdocs/js/lunr-0.5.7.min.js | 7 +
mkdocs/assets/search/mkdocs/js/mustache.min.js | 1 +
mkdocs/assets/search/mkdocs/js/require.js | 36 ++
.../mkdocs/js/search-results-template.mustache | 4 +
mkdocs/assets/search/mkdocs/js/search.js | 88 +++
mkdocs/assets/search/mkdocs/js/text.js | 390 +++++++++++++
mkdocs/build.py | 311 ++++++-----
mkdocs/cli.py | 197 +++++++
mkdocs/compat.py | 40 --
mkdocs/config.py | 159 ------
mkdocs/config/__init__.py | 5 +
mkdocs/config/base.py | 167 ++++++
mkdocs/config/config_options.py | 476 ++++++++++++++++
mkdocs/config/defaults.py | 119 ++++
mkdocs/exceptions.py | 14 +-
mkdocs/gh_deploy.py | 103 +++-
mkdocs/legacy.py | 125 +++++
mkdocs/main.py | 66 ---
mkdocs/nav.py | 196 ++++---
mkdocs/new.py | 29 +-
mkdocs/relative_path_ext.py | 137 +++++
mkdocs/search.py | 205 +++++++
mkdocs/serve.py | 165 +++---
mkdocs/templates/sitemap.xml | 20 +
mkdocs/test.py | 618 ---------------------
mkdocs/tests/__init__.py | 0
mkdocs/tests/base.py | 16 +
mkdocs/tests/build_tests.py | 376 +++++++++++++
mkdocs/tests/cli_tests.py | 70 +++
mkdocs/tests/config/__init__.py | 0
mkdocs/tests/config/base_tests.py | 54 ++
mkdocs/tests/config/config_options_tests.py | 518 +++++++++++++++++
mkdocs/tests/config/config_tests.py | 203 +++++++
mkdocs/tests/gh_deploy_tests.py | 100 ++++
mkdocs/tests/integration.py | 54 ++
mkdocs/tests/integration/minimal/docs/testing.md | 17 +
mkdocs/tests/integration/minimal/mkdocs.yml | 6 +
mkdocs/tests/legacy_tests.py | 64 +++
mkdocs/tests/nav_tests.py | 540 ++++++++++++++++++
mkdocs/tests/new_tests.py | 29 +
mkdocs/tests/search_tests.py | 140 +++++
mkdocs/tests/toc_tests.py | 134 +++++
mkdocs/tests/utils/__init__.py | 0
mkdocs/tests/utils/ghp_import_tests.py | 107 ++++
mkdocs/tests/utils/utils_tests.py | 158 ++++++
mkdocs/tests/yeti.zip | Bin 0 -> 266386 bytes
mkdocs/themes/amelia/base.html | 28 +-
mkdocs/themes/amelia/css/base.css | 14 +-
mkdocs/themes/{mkdocs => amelia}/css/highlight.css | 60 +-
mkdocs/themes/amelia/css/prettify-1.0.css | 28 -
mkdocs/themes/amelia/js/base.js | 41 +-
mkdocs/themes/amelia/js/highlight.pack.js | 2 +
mkdocs/themes/amelia/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/amelia/js/prettify-1.0.min.js | 28 -
mkdocs/themes/amelia/nav.html | 5 -
mkdocs/themes/bootstrap/base.html | 29 +-
mkdocs/themes/bootstrap/css/base.css | 14 +-
.../themes/{mkdocs => bootstrap}/css/highlight.css | 60 +-
mkdocs/themes/bootstrap/css/prettify-1.0.css | 28 -
mkdocs/themes/bootstrap/js/base.js | 42 +-
mkdocs/themes/bootstrap/js/highlight.pack.js | 2 +
mkdocs/themes/bootstrap/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/bootstrap/js/prettify-1.0.min.js | 28 -
mkdocs/themes/bootstrap/nav.html | 5 -
mkdocs/themes/cerulean/base.html | 28 +-
mkdocs/themes/cerulean/css/base.css | 14 +-
.../themes/{mkdocs => cerulean}/css/highlight.css | 60 +-
mkdocs/themes/cerulean/css/prettify-1.0.css | 28 -
mkdocs/themes/cerulean/js/base.js | 42 +-
mkdocs/themes/cerulean/js/highlight.pack.js | 2 +
mkdocs/themes/cerulean/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/cerulean/js/prettify-1.0.min.js | 28 -
mkdocs/themes/cerulean/nav.html | 5 -
mkdocs/themes/cosmo/base.html | 28 +-
mkdocs/themes/cosmo/css/base.css | 14 +-
mkdocs/themes/{mkdocs => cosmo}/css/highlight.css | 60 +-
mkdocs/themes/cosmo/css/prettify-1.0.css | 28 -
mkdocs/themes/cosmo/js/base.js | 42 +-
mkdocs/themes/cosmo/js/highlight.pack.js | 2 +
mkdocs/themes/cosmo/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/cosmo/js/prettify-1.0.min.js | 28 -
mkdocs/themes/cosmo/nav.html | 5 -
mkdocs/themes/cyborg/base.html | 28 +-
mkdocs/themes/cyborg/css/base.css | 14 +-
mkdocs/themes/{mkdocs => cyborg}/css/highlight.css | 60 +-
mkdocs/themes/cyborg/css/prettify-1.0.css | 28 -
mkdocs/themes/cyborg/js/base.js | 42 +-
mkdocs/themes/cyborg/js/highlight.pack.js | 2 +
mkdocs/themes/cyborg/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/cyborg/js/prettify-1.0.min.js | 28 -
mkdocs/themes/cyborg/nav.html | 5 -
mkdocs/themes/flatly/base.html | 28 +-
mkdocs/themes/flatly/css/base.css | 14 +-
mkdocs/themes/{mkdocs => flatly}/css/highlight.css | 60 +-
mkdocs/themes/flatly/css/prettify-1.0.css | 28 -
mkdocs/themes/flatly/js/base.js | 42 +-
mkdocs/themes/flatly/js/highlight.pack.js | 2 +
mkdocs/themes/flatly/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/flatly/js/prettify-1.0.min.js | 28 -
mkdocs/themes/flatly/nav.html | 5 -
mkdocs/themes/journal/base.html | 28 +-
mkdocs/themes/journal/css/base.css | 14 +-
.../themes/{mkdocs => journal}/css/highlight.css | 60 +-
mkdocs/themes/journal/css/prettify-1.0.css | 28 -
mkdocs/themes/journal/js/base.js | 42 +-
mkdocs/themes/journal/js/highlight.pack.js | 2 +
mkdocs/themes/journal/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/journal/js/prettify-1.0.min.js | 28 -
mkdocs/themes/journal/nav.html | 5 -
mkdocs/themes/mkdocs/base.html | 43 +-
mkdocs/themes/mkdocs/css/base.css | 110 +++-
mkdocs/themes/mkdocs/css/highlight.css | 60 +-
mkdocs/themes/mkdocs/css/prettify-1.0.css | 28 -
mkdocs/themes/mkdocs/js/base.js | 73 ++-
mkdocs/themes/mkdocs/js/highlight.pack.js | 3 +-
mkdocs/themes/mkdocs/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/mkdocs/js/prettify-1.0.min.js | 28 -
mkdocs/themes/mkdocs/nav-sub.html | 14 +
mkdocs/themes/mkdocs/nav.html | 55 +-
mkdocs/themes/mkdocs/search.html | 17 -
mkdocs/themes/readable/base.html | 28 +-
mkdocs/themes/readable/css/base.css | 14 +-
.../themes/{mkdocs => readable}/css/highlight.css | 60 +-
mkdocs/themes/readable/css/prettify-1.0.css | 28 -
mkdocs/themes/readable/js/base.js | 42 +-
mkdocs/themes/readable/js/highlight.pack.js | 2 +
mkdocs/themes/readable/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/readable/js/prettify-1.0.min.js | 28 -
mkdocs/themes/readable/nav.html | 5 -
mkdocs/themes/readthedocs/base.html | 68 ++-
mkdocs/themes/readthedocs/breadcrumbs.html | 27 +-
mkdocs/themes/readthedocs/css/highlight.css | 61 +-
mkdocs/themes/readthedocs/css/theme.css | 1 -
mkdocs/themes/readthedocs/css/theme_extra.css | 100 +++-
mkdocs/themes/readthedocs/footer.html | 5 +-
mkdocs/themes/readthedocs/js/highlight.pack.js | 3 +-
mkdocs/themes/readthedocs/js/jquery-2.1.1.min.js | 4 +
.../themes/readthedocs/js/modernizr-2.8.3.min.js | 1 +
mkdocs/themes/readthedocs/js/theme.js | 6 +
mkdocs/themes/readthedocs/search.html | 59 +-
mkdocs/themes/readthedocs/searchbox.html | 6 +-
mkdocs/themes/readthedocs/toc.html | 47 +-
mkdocs/themes/readthedocs/versions.html | 15 +
mkdocs/themes/simplex/base.html | 28 +-
mkdocs/themes/simplex/css/base.css | 14 +-
.../themes/{mkdocs => simplex}/css/highlight.css | 60 +-
mkdocs/themes/simplex/css/prettify-1.0.css | 28 -
mkdocs/themes/simplex/js/base.js | 42 +-
mkdocs/themes/simplex/js/highlight.pack.js | 2 +
mkdocs/themes/simplex/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/simplex/js/prettify-1.0.min.js | 28 -
mkdocs/themes/simplex/nav.html | 5 -
mkdocs/themes/slate/base.html | 28 +-
mkdocs/themes/slate/css/base.css | 14 +-
mkdocs/themes/{mkdocs => slate}/css/highlight.css | 60 +-
mkdocs/themes/slate/css/prettify-1.0.css | 28 -
mkdocs/themes/slate/js/base.js | 42 +-
mkdocs/themes/slate/js/highlight.pack.js | 2 +
mkdocs/themes/slate/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/slate/js/prettify-1.0.min.js | 28 -
mkdocs/themes/slate/nav.html | 5 -
mkdocs/themes/spacelab/base.html | 28 +-
mkdocs/themes/spacelab/css/base.css | 14 +-
.../themes/{mkdocs => spacelab}/css/highlight.css | 60 +-
mkdocs/themes/spacelab/css/prettify-1.0.css | 28 -
mkdocs/themes/spacelab/js/base.js | 42 +-
mkdocs/themes/spacelab/js/highlight.pack.js | 2 +
mkdocs/themes/spacelab/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/spacelab/js/prettify-1.0.min.js | 28 -
mkdocs/themes/spacelab/nav.html | 5 -
mkdocs/themes/united/base.html | 28 +-
mkdocs/themes/united/css/base.css | 14 +-
mkdocs/themes/{mkdocs => united}/css/highlight.css | 60 +-
mkdocs/themes/united/css/prettify-1.0.css | 28 -
mkdocs/themes/united/js/base.js | 42 +-
mkdocs/themes/united/js/highlight.pack.js | 2 +
mkdocs/themes/united/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/united/js/prettify-1.0.min.js | 28 -
mkdocs/themes/united/nav.html | 5 -
mkdocs/themes/yeti/base.html | 28 +-
mkdocs/themes/yeti/css/base.css | 14 +-
mkdocs/themes/{mkdocs => yeti}/css/highlight.css | 60 +-
mkdocs/themes/yeti/css/prettify-1.0.css | 28 -
mkdocs/themes/yeti/js/base.js | 42 +-
mkdocs/themes/yeti/js/highlight.pack.js | 2 +
mkdocs/themes/yeti/js/jquery-1.10.2.min.js | 6 +
mkdocs/themes/yeti/js/prettify-1.0.min.js | 28 -
mkdocs/themes/yeti/nav.html | 5 -
mkdocs/toc.py | 75 ++-
mkdocs/utils.py | 161 ------
mkdocs/utils/__init__.py | 398 +++++++++++++
mkdocs/utils/ghp_import.py | 173 ++++++
requirements.txt | 5 -
requirements/packaging.txt | 6 +
requirements/project.txt | 6 +
test-requirements.txt => requirements/test.txt | 1 +
setup.cfg | 2 +
setup.py | 77 +--
tox.ini | 28 +-
216 files changed, 8275 insertions(+), 3732 deletions(-)
diff --git a/.travis.sh b/.travis.sh
deleted file mode 100755
index ab95ebb..0000000
--- a/.travis.sh
+++ /dev/null
@@ -1,10 +0,0 @@
-#! /usr/bin/env bash
-set -xe
-if [ $TOX_ENV == "coverage" ]
-then
- pip install coveralls
- tox -e py27
- coveralls
-else
- tox -e $TOX_ENV
-fi
diff --git a/.travis.yml b/.travis.yml
index e53a24f..ed0e426 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,17 +1,19 @@
language: python
-python: "2.7"
+python: '2.7'
env:
-- TOX_ENV=py26
-- TOX_ENV=py27
-- TOX_ENV=py33
-- TOX_ENV=py34
-- TOX_ENV=flake8
-- TOX_ENV=docs
-- TOX_ENV=json
-- TOX_ENV=coverage
+- TOXENV=py26-unittests
+- TOXENV=py27-unittests
+- TOXENV=py33-unittests
+- TOXENV=py34-unittests
+- TOXENV=py26-integration
+- TOXENV=py27-integration
+- TOXENV=py33-integration
+- TOXENV=py34-integration
+- TOXENV=flake8
install:
- pip install tox
-script: "./.travis.sh"
+script: tox
matrix:
- allow_failures:
- - env: TOXENV=coverage
+ fast_finish: true
+before_install: pip install codecov
+after_success: codecov
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3710c7b
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,6 @@
+# Contributing to MkDocs
+
+See the contributing guide in the documentation for an
+introduction to contributing to MkDocs.
+
+http://www.mkdocs.org/about/contributing/
diff --git a/README.md b/README.md
index 0291b5d..2d24ad6 100644
--- a/README.md
+++ b/README.md
@@ -2,18 +2,35 @@
**Project documentation with Markdown.**
+[![PyPI Downloads][pypi-dl-image]][pypi-dl-link]
+[![PyPI Version][pypi-v-image]][pypi-v-link]
[![Build Status][travis-image]][travis-link]
-[![Coverage Status][coveralls-image]][coveralls-link]
+[![Windows Build Status][appveyor-image]][appveyor-link]
+[![Coverage Status][codecov-image]][codecov-link]
+[![Landscale Code Health][landscape-image]][landscape-link]
-Background: https://groups.google.com/forum/#!topic/django-rest-framework/YJ6J3jocGlo
+**See the MkDocs documentation: [www.mkdocs.org][mkdocs]**
-**See in progress docs: [www.mkdocs.org](http://www.mkdocs.org)**
+Release notes: http://www.mkdocs.org/about/release-notes/
-Project roadmap: [https://github.com/tomchristie/mkdocs/wiki](https://github.com/tomchristie/mkdocs/wiki)
+Project roadmap: [https://github.com/mkdocs/mkdocs/wiki][roadmap]
IRC channel: `#mkdocs` on freenode.
-[travis-image]: https://travis-ci.org/tomchristie/mkdocs.png?branch=master
-[travis-link]: https://travis-ci.org/tomchristie/mkdocs
-[coveralls-image]: https://coveralls.io/repos/tomchristie/mkdocs/badge.png?branch=master
-[coveralls-link]: https://coveralls.io/r/tomchristie/mkdocs?branch=master
+Discussions and support: https://groups.google.com/forum/#!forum/mkdocs
+
+[appveyor-image]: https://img.shields.io/appveyor/ci/d0ugal/mkdocs/master.png
+[appveyor-link]: https://ci.appveyor.com/project/d0ugal/mkdocs
+[codecov-image]: http://codecov.io/github/mkdocs/mkdocs/coverage.svg?branch=master
+[codecov-link]: http://codecov.io/github/mkdocs/mkdocs?branch=master
+[landscape-image]: https://landscape.io/github/mkdocs/mkdocs/master/landscape.svg?style=flat-square
+[landscape-link]: https://landscape.io/github/mkdocs/mkdocs/master
+[pypi-dl-image]: https://img.shields.io/pypi/dm/mkdocs.png
+[pypi-dl-link]: https://pypi.python.org/pypi/mkdocs
+[pypi-v-image]: https://img.shields.io/pypi/v/mkdocs.png
+[pypi-v-link]: https://pypi.python.org/pypi/mkdocs
+[travis-image]: https://img.shields.io/travis/mkdocs/mkdocs/master.png
+[travis-link]: https://travis-ci.org/mkdocs/mkdocs
+
+[mkdocs]: http://www.mkdocs.org
+[roadmap]: https://github.com/mkdocs/mkdocs/wiki
diff --git a/appveyor.yml b/appveyor.yml
new file mode 100644
index 0000000..4ef8228
--- /dev/null
+++ b/appveyor.yml
@@ -0,0 +1,23 @@
+build: false
+environment:
+ matrix:
+ - TOXENV: py27-unittests
+ - TOXENV: py33-unittests
+ - TOXENV: py34-unittests
+ - TOXENV: py27-integration
+ - TOXENV: py33-integration
+ - TOXENV: py34-integration
+ - TOXENV: flake8
+init:
+ - "ECHO %TOXENV%"
+ - ps: "ls C:\\Python*"
+install:
+ - ps: Invoke-WebRequest "https://bootstrap.pypa.io/ez_setup.py" -OutFile "c:\\ez_setup.py"
+ - ps: Invoke-WebRequest "https://bootstrap.pypa.io/get-pip.py" -OutFile "c:\\get-pip.py"
+ - "c:\\python27\\python c:\\ez_setup.py"
+ - "c:\\python27\\python c:\\get-pip.py"
+ - "c:\\python27\\Scripts\\pip install tox"
+test_script:
+ - "c:\\python27\\Scripts\\tox --version"
+ - "c:\\python27\\Scripts\\pip --version"
+ - "c:\\python27\\Scripts\\tox"
diff --git a/docs/about/contributing.md b/docs/about/contributing.md
new file mode 100644
index 0000000..8e360b9
--- /dev/null
+++ b/docs/about/contributing.md
@@ -0,0 +1,65 @@
+# Contributing to MkDocs
+
+An introduction to contributing to the MkDocs project.
+
+The MkDocs project welcomes, and depends, on contributions from developers and
+users in the open source community. Contributions can be made in a number of
+ways, a few examples are:
+
+- Code patches via pull requests
+- Documentation improvements
+- Bug reports and patch reviews
+
+## Reporting an Issue?
+
+Please include as much detail as you can. Let us know your platform and MkDocs
+version. If the problem is visual (for example a theme or design issue) please
+add a screenshot and if you get an error please include the the full error and
+traceback.
+
+
+## Testing the Development Version
+
+If you want to just install and try out the latest development version of
+MkDocs you can do so with the following command. This can be useful if you
+want to provide feedback for a new feature or want to confirm if a bug you
+have encountered is fixed in the git master. It is **strongly** recommended
+that you do this within a [virtualenv].
+
+```bash
+pip install https://github.com/mkdocs/mkdocs/archive/master.tar.gz
+```
+
+## Installing for Development
+
+First you'll need to fork and clone the repository. Once you have a local
+copy, run the following command. It is **strongly** recommended that you do
+this within a [virtualenv].
+
+```bash
+pip install --editable .
+```
+
+This will install MkDocs in development mode which binds the `mkdocs` command
+to the git repository.
+
+
+## Running the tests
+
+To run the tests, it is recommended that you use [Tox]. This just needs
+to be pip installed and then the test suite can be ran for MkDocs but running
+the command `tox` in the root of your MkDocs repository.
+
+It will attempt to run the tests against all of the Python versions we
+support. So don't be concerned if you are missing some and they fail. The rest
+will be verified by [Travis] when you submit a pull request.
+
+## Submitting Pull Requests
+
+Once you are happy with your changes or you are ready for some feedback, push
+it to your fork and send a pull request. For a change to be accepted it will
+most likely need to have tests and documentation if it is a new feature.
+
+[virtualenv]: https://virtualenv.pypa.io/en/latest/userguide.html
+[tox]: https://tox.readthedocs.org/en/latest/
+[travis]: https://travis-ci.org/repositories
diff --git a/docs/about/license.md b/docs/about/license.md
index 1e5eb63..c99eb25 100644
--- a/docs/about/license.md
+++ b/docs/about/license.md
@@ -10,7 +10,6 @@ Themes used under license from the Bootstrap, ReadTheDocs, GhostWriter and Boots
* Bootstrap theme - [View license](//github.com/twbs/bootstrap/blob/master/LICENSE).
* ReadTheDocs theme - [View license](//github.com/snide/sphinx_rtd_theme/blob/master/LICENSE).
-* GhostWriter theme - [View license](//github.com/roryg/ghostwriter/blob/master/LICENSE.txt).
* Bootswatch theme - [View license](//github.com/thomaspark/bootswatch/blob/gh-pages/LICENSE).
* Highlight.js GitHub theme - [View license](//github.com/isagalaev/highlight.js/blob/master/LICENSE).
diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md
index ac53093..099571a 100644
--- a/docs/about/release-notes.md
+++ b/docs/about/release-notes.md
@@ -8,33 +8,239 @@ To upgrade MkDocs to the latest version, use pip:
pip install -U mkdocs
-You can determine your currently installed version using `pip freeze`:
+You can determine your currently installed version using `mkdocs --version`:
- pip freeze | grep mkdocs
+ $ mkdocs --version
+ mkdocs, version 0.14.0
-## 0.11.1 (2014-11-20)
+## Version 0.14.0 (2015-06-09)
+
+* Improve Unicode handling by ensuring that all config strings are loaded as
+ Unicode. (#592)
+* Remove dependancy on the six library. (#583)
+* Remove dependancy on the ghp-import library. (#547)
+* Add `--quiet` and `--verbose` options to all subcommands. (#579)
+* Add short options (`-a`) to most command line options. (#579)
+* Add copyright footer for readthedocs theme. (#568)
+* If the requested port in `mkdocs serve` is already in use, don't show the
+ user a full stack trace. (#596)
+* Bugfix: Fix a JavaScript encoding problem when searching with spaces. (#586)
+* Bugfix: gh-deploy now works if the mkdocs.yml is not in the git repo root.
+ (#578)
+* Bugfix: Handle (pass-through instead of dropping) HTML entities while
+ parsing TOC. (#612)
+* Bugfix: Default extra_templates to an empty list, don't automatically
+ discover them. (#616)
+
+## Version 0.13.3 (2015-06-02)
+
+* Bugfix: Reduce validation error to a warning if the site_dir is within
+ the docs_dir as this shouldn't cause any problems with building but will
+ inconvenience users building multiple times. (#580)
+
+## Version 0.13.2 (2015-05-30)
+
+* Bugfix: Ensure all errors and warnings are logged before exiting. (#536)
+* Bugfix: Fix compatibility issues with ReadTheDocs. (#554)
+
+## Version 0.13.1 (2015-05-27)
+
+* Bugfix: Fix a problem with minimal configurations which only contain a list
+ of paths in the pages config. (#562)
+
+
+## Version 0.13.0 (2015-05-26)
+
+### Deprecations
+
+#### Deprecate the JSON command
+
+In this release the `mkdocs json` command has been marked as deprecated and
+when used a deprecation warning will be shown. It will be removed in a [future
+release] of MkDocs, version 1.0 at the latest. The `mkdocs json` command
+provided a convenient way for users to output the documentation contents as
+JSON files but with the additions of search to MkDocs this functionality is
+duplicated.
+
+A new index with all the contents from a MkDocs build is created in the
+[site_dir], so with the default value for the `site_dir` It can be found in
+`site/mkdocs/search_index.json`.
+
+This new file is created on every MkDocs build (with `mkdocs build`) and
+no configuration is needed to enable it.
+
+[future release]: https://github.com/mkdocs/mkdocs/pull/481
+[site_dir]: /user-guide/configuration/#site_dir
+
+#### Change the pages configuration
+
+Provide a [new way] to define pages, and specifically [nested pages], in the
+mkdocs.yml file and deprecate the existing approach, support will be removed
+with MkDocs 1.0.
+
+[new way]: /user-guide/writing-your-docs/#configure-pages-and-navigation
+[nested pages]: /user-guide/writing-your-docs/#multilevel-documentation
+
+#### Warn users about the removal of builtin themes
+
+All themes other than mkdocs and readthedocs will be moved into external
+packages in a future release of MkDocs. This will enable them to be more easily
+supported and updates outside MkDocs releases.
+
+
+### Major Additions
+
+#### Search
+
+Support for search has now been added to MkDocs. This is based on the
+JavaScript library [lunr.js]. It has been added to both the `mkdocs` and
+`readthedocs` themes. See the custom theme documentation on [supporting search]
+for adding it to your own themes.
+
+[lunr.js]: http://lunrjs.com/
+[supporting search]: /user-guide/styling-your-docs/#search-and-themes
+
+#### New Command Line Interface
+
+The command line interface for MkDocs has been re-written with the Python
+library [Click]. This means that MkDocs now has an easier to use interface
+with better help output.
+
+This change is partially backwards incompatible as while undocumented it was
+possible to pass any configuration option to the different commands. Now only
+a small subset of the configuration options can be passed to the commands. To
+see in full commands and available arguments use `mkdocs --help` and
+`mkdocs build --help` to have them displayed.
+
+[Click]: http://click.pocoo.org/4/
+
+#### Support Extra HTML and XML files
+
+Like the [extra_javascript] and [extra_css] configuration options, a new
+option named [extra_templates] has been added. This will automatically be
+populated with any `.html` or `.xml` files in the project docs directory.
+
+Users can place static HTML and XML files and they will be copied over, or they
+can also use Jinja2 syntax and take advantage of the [global variables].
+
+By default MkDocs will use this approach to create a sitemap for the
+documentation.
+
+[extra_javascript]: /user-guide/configuration/#extra_javascript
+[extra_css]: /user-guide/configuration/#extra_css
+[extra_templates]: /user-guide/configuration/#extra_templates
+[global variables]: /user-guide/styling-your-docs/#global-context
+
+### Other Changes and Additions
+
+* Add support for [Markdown extension configuration options]. (#435)
+* MkDocs now ships Python [wheels]. (#486)
+* Only include the build date and MkDocs version on the homepage. (#490)
+* Generate sitemaps for documentation builds. (#436)
+* Add a clearer way to define nested pages in the configuration. (#482)
+* Add an [extra config] option for passing arbitrary variables to the template. (#510)
+* Add `--no-livereload` to `mkdocs serve` for a simpler development server. (#511)
+* Add copyright display support to all themes (#549)
+* Add support for custom commit messages in a `mkdocs gh-deploy` (#516)
+* Bugfix: Fix linking to media within the same directory as a markdown file called index.md (#535)
+* Bugfix: Fix errors with unicode filenames (#542).
+
+[extra config]: /user-guide/configuration/#extra
+[Markdown extension configuration options]: /user-guide/configuration/#markdown_extensions
+[wheels]: http://pythonwheels.com/
+
+
+## Version 0.12.2 (2015-04-22)
+
+* Bugfix: Fix a regression where there would be an error if some child titles
+ were missing but others were provided in the pages config. (#464)
+
+
+## Version 0.12.1 (2015-04-14)
+
+* Bugfix: Fixed a CSS bug in the table of contents on some browsers where the
+ bottom item was not clickable.
+
+
+## Version 0.12.0 (2015-04-14)
+
+* Display the current MkDocs version in the CLI output. (#258)
+* Check for CNAME file when using gh-deploy. (#285)
+* Add the homepage back to the navigation on all themes. (#271)
+* Add a strict more for local link checking. (#279)
+* Add Google analytics support to all themes. (#333)
+* Add build date and MkDocs version to the ReadTheDocs and MkDocs theme
+ outputs. (#382)
+* Standardise highlighting across all themes and add missing languages. (#387)
+* Add a verbose flag. (-v) to show more details about what the build. (#147)
+* Add the option to specify a remote branch when deploying to GitHub. This
+ enables deploying to GitHub pages on personal and repo sites. (#354)
+* Add favicon support to the ReadTheDocs theme HTML. (#422)
+* Automatically refresh the browser when files are edited. (#163)
+* Bugfix: Never re-write URL's in code blocks. (#240)
+* Bugfix: Don't copy ditfiles when copying media from the `docs_dir`. (#254)
+* Bugfix: Fix the rendering of tables in the ReadTheDocs theme. (#106)
+* Bugfix: Add padding to the bottom of all bootstrap themes. (#255)
+* Bugfix: Fix issues with nested Markdown pages and the automatic pages
+ configuration. (#276)
+* Bugfix: Fix a URL parsing error with GitHub enterprise. (#284)
+* Bugfix: Don't error if the mkdocs.yml is completely empty. (#288)
+* Bugfix: Fix a number of problems with relative urls and Markdown files. (#292)
+* Bugfix: Don't stop the build if a page can't be found, continue with other
+ pages. (#150)
+* Bugfix: Remove the site_name from the page title, this needs to be added
+ manually. (#299)
+* Bugfix: Fix an issue with table of contents cutting off Markdown. (#294)
+* Bugfix: Fix hostname for BitBucket. (#339)
+* Bugfix: Ensure all links end with a slash. (#344)
+* Bugfix: Fix repo links in the readthedocs theme. (#365)
+* Bugfix: Include jQuery locally to avoid problems using MkDocs offline. (#143)
+* Bugfix: Don't allow the docs_dir to be in the site_dir or vice versa. (#384)
+* Bugfix: Remove inline CSS in the ReadTheDocs theme. (#393)
+* Bugfix: Fix problems with the child titles due to the order the pages config
+ was processed. (#395)
+* Bugfix: Don't error during live reload when the theme doesn't exist. (#373)
+* Bugfix: Fix problems with the Meta extension when it may not exist. (#398)
+* Bugfix: Wrap long inline code otherwise they will run off the screen. (#313)
+* Bugfix: Remove HTML parsing regular expressions and parse with HTMLParser to
+ fix problems with titles containing code. (#367)
+* Bugfix: Fix an issue with the scroll to anchor causing the title to be hidden
+ under the navigation. (#7)
+* Bugfix: Add nicer CSS classes to the HTML tables in bootswatch themes. (#295)
+* Bugfix: Fix an error when passing in a specific config file with
+ `mkdocs serve`. (#341)
+* Bugfix: Don't overwrite index.md diles with the `mkdocs new` command. (#412)
+* Bugfix: Remove bold and italic from code in the ReadTheDocs theme. (#411)
+* Bugfix: Display images inline in the MkDocs theme. (#415)
+* Bugfix: Fix problems with no-highlight in the ReadTheDocs theme. (#319)
+* Bugfix: Don't delete hidden files when using `mkdocs build --clean`. (#346)
+* Bugfix: Don't block newer verions of Python-markdown on Python >= 2.7. (#376)
+* Bugfix: Fix encoding issues when opening files across platforms. (#428)
+
+
+## Version 0.11.1 (2014-11-20)
* Bugfix: Fix a CSS wrapping issue with code highlighting in the ReadTheDocs
theme. (#233)
-## 0.11.0 (2014-11-18)
+## Version 0.11.0 (2014-11-18)
-* Render 404.html files if they exist for the current theme (#194)
+* Render 404.html files if they exist for the current theme. (#194)
* Bugfix: Fix long nav bars, table rendering and code highlighting in MkDocs
- and ReadTheDocs themes (#225)
+ and ReadTheDocs themes. (#225)
* Bugfix: Fix an issue with the google_analytics code. (#219)
* Bugfix: Remove `__pycache__` from the package tar. (#196)
-* Bugfix: Fix markdown links that go to an anchor on the current page (#197)
+* Bugfix: Fix markdown links that go to an anchor on the current page. (#197)
* Bugfix: Don't add `prettyprint well` CSS classes to all HTML, only add it in
- the MkDocs theme (#183)
-* Bugfix: Display section titles in the ReadTheDocs theme (#175)
+ the MkDocs theme. (#183)
+* Bugfix: Display section titles in the ReadTheDocs theme. (#175)
* Bugfix: Use the polling observer in watchdog so rebuilding works on
filesystems without inotify. (#184)
* Bugfix: Improve error output for common configuration related errors. (#176)
-## 0.10.0 (2014-10-29)
+## Version 0.10.0 (2014-10-29)
* Added support for Python 3.3 and 3.4. (#103)
* Configurable Python-Markdown extensions with the config setting
@@ -42,7 +248,7 @@ You can determine your currently installed version using `pip freeze`:
* Added `mkdocs json` command to output your rendered
documentation as json files. (#128)
* Added `--clean` switch to `build`, `json` and `gh-deploy` commands to
- remove stale files from the output directory (#157)
+ remove stale files from the output directory. (#157)
* Support multiple theme directories to allow replacement of
individual templates rather than copying the full theme. (#129)
* Bugfix: Fix `<ul>` rendering in readthedocs theme. (#171)
@@ -51,10 +257,9 @@ You can determine your currently installed version using `pip freeze`:
* Bugfix: Fix issue rendering the table of contents with some configs. (#146)
* Bugfix: Fix path for embedded images in sub pages. (#138)
* Bugfix: Fix `use_directory_urls` config behaviour. (#63)
-* Bugfix: Support `extra_javascript` and `extra_css` in all themes (#90)
+* Bugfix: Support `extra_javascript` and `extra_css` in all themes. (#90)
* Bugfix: Fix path-handling under Windows. (#121)
* Bugfix: Fix the menu generation in the readthedocs theme. (#110)
* Bugfix: Fix the mkdocs command creation under Windows. (#122)
* Bugfix: Correctly handle external `extra_javascript` and `extra_css`. (#92)
* Bugfix: Fixed favicon support. (#87)
-
diff --git a/docs/css/extra.css b/docs/css/extra.css
index 81a2bfe..c1b6d58 100644
--- a/docs/css/extra.css
+++ b/docs/css/extra.css
@@ -3,6 +3,15 @@ div.col-md-9 h1:first-of-type {
font-size: 60px;
font-weight: 300;
}
+
div.col-md-9 p:first-of-type {
text-align: center;
}
+
+div.col-md-9 p.admonition-title:first-of-type {
+ text-align: left;
+}
+
+div.col-md-9 h1:first-of-type .headerlink {
+ display: none;
+}
diff --git a/docs/img/mkdocs.png b/docs/img/mkdocs.png
new file mode 100644
index 0000000..9d3a321
Binary files /dev/null and b/docs/img/mkdocs.png differ
diff --git a/docs/index.md b/docs/index.md
index 42357df..efa22f6 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -12,7 +12,7 @@ MkDocs is a **fast**, **simple** and **downright gorgeous** static site generato
**MkDocs is currently still in development.**
-We're progressing quickly, but the documentation still needs filling in, and theres a few rough edges. The 1.0 release is planned to arrive in the next few weeks.
+We're progressing quickly, but the documentation still needs filling in, and there are a few rough edges. The 1.0 release is planned to arrive in the next few months.
---
@@ -22,7 +22,7 @@ Builds completely static HTML sites that you can host on GitHub pages, Amazon S3
#### Great themes available.
-There's a stack of good looking themes included by default. Choose from bootstrap, readthedocs, ghostwriter, or any of the 12 bootswatch themes.
+There's a stack of good looking themes included by default. Choose from bootstrap, readthedocs, or any of the 12 bootswatch themes.
#### Preview your site as you work.
@@ -32,15 +32,11 @@ The built-in devserver allows you to preview your documentation as you're writin
Get your project documentation looking just the way you want it by customizing the theme.
-#### Cross-reference your documentation.
-
-Create richly cross-referenced documents, using the MkDocs interlinking syntax.
-
---
## Installation
-In order to install MkDocs you'll need [Python][python] installed on your system, as well as the Python package manager, [pip][pip]. You can check if you have these already installed like so:
+In order to install MkDocs you'll need [Python] installed on your system, as well as the Python package manager, [pip]. You can check if you have these already installed like so:
$ python --version
Python 2.7.2
@@ -49,6 +45,8 @@ In order to install MkDocs you'll need [Python][python] installed on your system
MkDocs supports Python 2.6, 2.7, 3.3 and 3.4.
+On Windows we recommend that you install Python and pip with [Chocolatey].
+
Install the `mkdocs` package using pip:
$ pip install mkdocs
@@ -60,6 +58,7 @@ You should now have the `mkdocs` command installed on your system. Run `mkdocs
---
+
## Getting started
Getting started is super easy.
@@ -106,8 +105,8 @@ We'd like our documentation site to include some navigation headers, so we'll ed
site_name: MkLorum
pages:
- - [index.md, Home]
- - [about.md, About]
+ - Home: index.md
+ - About: about.md
Refresh the browser and you'll now see a navigation bar with `Home` and `About` headers.
@@ -117,10 +116,11 @@ While we're here can also change the configuration file to alter how the documen
site_name: MkLorum
pages:
- - [index.md, Home]
- - [about.md, About]
+ - Home: index.md
+ - About: about.md
theme: readthedocs
+
Refresh the browser again, and you'll now see the ReadTheDocs theme being used.
@@ -148,9 +148,25 @@ After some time, files may be removed from the documentation but they will still
$ mkdocs build --clean
+
## Deploying
-The documentation site that we've just built only uses static files so you'll be able to host it from pretty much anywhere. [GitHub project pages](https://help.github.com/articles/creating-project-pages-manually) and [Amazon S3](http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html) are good hosting options. Upload the contents of the entire `site` directory to wherever you're hosting your website from and you're done.
+The documentation site that we've just built only uses static files so you'll be
+able to host it from pretty much anywhere. [GitHub project pages] and [Amazon
+S3] are good hosting options. Upload the contents of the entire `site` directory
+to wherever you're hosting your website from and you're done. For specific instructions
+for a number of common hosts, see the [Deploying your Docs] page.
+
+
+## Getting help
+
+To get help with MkDocs, please use the [discussion group], [GitHub issues] or the MkDocs IRC channel `#mkdocs` on freenode.
-[python]: https://www.python.org/
+[Amazon S3]: http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html
+[Chocolatey]: https://chocolatey.org/
+[discussion group]: https://groups.google.com/forum/#!forum/mkdocs
+[GitHub issues]: https://github.com/mkdocs/mkdocs/issues
+[GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually
[pip]: http://pip.readthedocs.org/en/latest/installing.html
+[Python]: https://www.python.org/
+[Deploying your Docs]: user-guide/deploying-your-docs/
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 3c1ebd1..041f3fd 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -8,25 +8,25 @@ Guide to all available configuration settings.
Project settings are always configured by using a YAML configuration file in the project directory named `mkdocs.yml`.
-As a miniumum this configuration file must contain the `site_name` setting. All other settings are optional.
+As a minimum this configuration file must contain the `site_name` setting. All other settings are optional.
## Project information
-#### site_name
+### site_name
This is a **required setting**, and should be a string that is used as the main title for the project documentation. For example:
- site_name: Mashmallow Generator
+ site_name: Marshmallow Generator
When rendering the theme this setting will be passed as the `site_name` context variable.
-#### site_url
+### site_url
Set the canonical URL of the site. This will add a link tag with the canonical URL to the generated HTML header.
**default**: `null`
-#### repo_url
+### repo_url
When set, provides a link to your GitHub or Bitbucket repository on each page.
@@ -34,18 +34,24 @@ When set, provides a link to your GitHub or Bitbucket repository on each page.
**default**: `null`
-#### site_description
+### repo_name
+
+When set, provides a link to your GitHub or Bitbucket repository on each page.
+
+**default**: `'GitHub'` or `'Bitbucket'` if the `repo_url` matches those domains, otherwise `null`
+
+### site_description
Set the site description. This will add a meta tag to the generated HTML header.
**default**: `null`
-#### site_author
+### site_author
Set the name of the author. This will add a meta tag to the generated HTML header.
**default**: `null`
-#### site_favicon
+### site_favicon
Set the favicon to use. Putting a `favicon.ico` into the `docs/` directory, the config would look as follows:
@@ -55,104 +61,127 @@ site_favicon: favicon.ico
**default**: `null`
-## Documentation layout
-#### pages
+### copyright
-This is setting is used to determine the set of pages that should be built for the documentation.
+Set the copyright information to be included in the documentation by the theme.
-The setting should be a list. Each row in the list represents information about a single page as a list of strings. The first string represents the path of the documentation source file, and should be relative to the `docs_dir` setting. Remaining strings represent the title of the page in the site navigation.
+**default**: `null`
-Here's a simple example that would cause the build stage to create three pages:
- pages:
- - ['index.md', 'Introduction']
- - ['user-guide.md', 'User Guide']
- - ['about.md', 'About']
+### google_analytics
+
+Set the Google analytics tracking configuration.
+
+```yaml
+google_analytics: ['UA-36723568-3', 'mkdocs.org']
+```
+
+**default**: `null`
-Assuming the `docs_dir` setting was left with the default value of `docs`, the source files for this site's build process would be `docs/index.md`, `docs/user-guide.md` and `docs/about.md`.
-If you have a lot of project documentation you might choose to use headings to break up your site navigation by category. You can do so by including an extra string in the page configuration for any pages that require a navigation heading, like so:
+### remote_branch
+
+Set the remote branch to commit to when using `gh-deploy` to deploy to Github Pages. This option can be overridden by a command line option in `gh-deploy`.
+
+**default**: `gh-pages`
+
+
+### remote_name
+
+Set the remote name to push to when using `gh-deploy` to deploy to Github Pages. This option can be overridden by a command line option in `gh-deploy`.
+
+**default**: `gh-pages`
+
+
+## Documentation layout
+
+### pages
+
+This setting is used to determine the set of pages that should be built for the documentation. For example, the following would create Introduction, User Guide and About pages, given the three source files `index.md`, `user-guide.md` and `about.md`, respectively.
pages:
- - ['index.md', 'Introduction']
- - ['user-guide/creating.md', 'User Guide', 'Creating a new Mashmallow project']
- - ['user-guide/api.md', 'User Guide', 'Mashmallow API guide']
- - ['user-guide/configuration.md', 'User Guide', 'Configuring Mashmallow']
- - ['about/license.md', 'About', 'License']
+ - 'Introduction': 'index.md'
+ - 'User Guide': 'user-guide.md'
+ - 'About': 'about.md'
+
+See the section on [configuring pages and navigation](/user-guide/writing-your-docs/#configure-pages-and-navigation) for a more detailed breakdown, including how to create sub-sections.
## Build directories
-#### theme
+
+### theme
Sets the theme of your documentation site, for a list of available themes visit
[styling your docs](styling-your-docs.md).
**default**: `'mkdocs'`
-#### theme_dir
-Lets you set a directory to a custom theme. This can either be a relative directory, in which case it is resolved relative to the directory containing you configuration file, or it can be an absolute directory path.
+### theme_dir
... 15586 lines suppressed ...
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/python-modules/packages/python-mkdocs.git
More information about the Python-modules-commits
mailing list