[Python-modules-commits] [python-mkdocs] 03/06: New upstream version 0.16.1
Brian May
bam at moszumanska.debian.org
Thu Mar 9 10:14:28 UTC 2017
This is an automated email from the git hooks/post-receive script.
bam pushed a commit to branch debian/experimental
in repository python-mkdocs.
commit ebf5a08d24c89ab0ed0c11479654035ce2971178
Author: Brian May <bam at debian.org>
Date: Thu Mar 9 20:55:43 2017 +1100
New upstream version 0.16.1
---
.codecov.yml | 11 +
.csslintrc | 45 +++
.jshintignore | 7 +
.travis.yml | 14 +-
MANIFEST.in | 4 +-
README.md | 20 +-
docs/about/contributing.md | 8 +-
docs/about/license.md | 8 +-
docs/about/release-notes.md | 219 ++++++++++-
docs/img/initial-config.png | Bin 13926 -> 0 bytes
docs/img/multipage.png | Bin 0 -> 31289 bytes
docs/img/readthedocs.png | Bin 84400 -> 70346 bytes
docs/img/screenshot.png | Bin 110703 -> 79740 bytes
docs/img/search.png | Bin 0 -> 101853 bytes
docs/img/site-name.png | Bin 28320 -> 13225 bytes
docs/img/win-py-install.png | Bin 0 -> 41678 bytes
docs/index.md | 246 ++++++++----
docs/user-guide/configuration.md | 110 ++++--
docs/user-guide/custom-themes.md | 247 +++++++-----
docs/user-guide/deploying-your-docs.md | 27 +-
docs/user-guide/styling-your-docs.md | 285 ++++++++++----
docs/user-guide/writing-your-docs.md | 11 +-
mkdocs.yml | 7 +-
mkdocs/__init__.py | 2 +-
mkdocs/__main__.py | 71 ++--
mkdocs/assets/search/mkdocs/js/lunr-0.5.7.min.js | 7 -
mkdocs/assets/search/mkdocs/js/lunr.min.js | 7 +
mkdocs/assets/search/mkdocs/js/search.js | 4 +-
mkdocs/commands/build.py | 210 +++++++---
mkdocs/commands/gh_deploy.py | 55 +--
mkdocs/commands/serve.py | 10 +-
mkdocs/config/base.py | 42 +-
mkdocs/config/config_options.py | 85 +++--
mkdocs/config/defaults.py | 10 +-
mkdocs/nav.py | 43 ++-
mkdocs/templates/sitemap.xml | 4 +-
mkdocs/tests/build_tests.py | 43 ++-
mkdocs/tests/cli_tests.py | 422 ++++++++++++++++++++-
mkdocs/tests/config/base_tests.py | 184 ++++++++-
mkdocs/tests/config/config_options_tests.py | 53 ++-
mkdocs/tests/config/config_tests.py | 14 +-
mkdocs/tests/gh_deploy_tests.py | 20 +-
mkdocs/tests/integration.py | 27 +-
.../complicated_config/documentation/custom.html | 9 +
.../complicated_config/documentation/index.md | 4 +
.../complicated_config/documentation/tweak.css | 3 +
.../complicated_config/documentation/tweak.js | 1 +
.../integration/complicated_config/mkdocs.yml | 45 +++
.../complicated_config/theme_tweaks/404.html | 7 +
.../tests/integration/subpages/docs/image.png | Bin
mkdocs/tests/integration/subpages/docs/index.md | 23 ++
.../tests/integration/subpages/docs/non-index.md | 23 ++
.../tests/integration/subpages/docs/sub1/image.png | Bin 0 -> 14085 bytes
.../tests/integration/subpages/docs/sub1/index.md | 38 ++
.../integration/subpages/docs/sub1/non-index.md | 38 ++
.../integration/subpages/docs/sub1/sub1a/index.md | 30 ++
.../subpages/docs/sub1/sub1a/non-index.md | 30 ++
.../tests/integration/subpages/docs/sub2/index.md | 31 ++
.../integration/subpages/docs/sub2/non-index.md | 31 ++
mkdocs/tests/integration/subpages/mkdocs.yml | 1 +
mkdocs/tests/integration/unicode/docs/index.md | 2 +
.../integration/unicode/docs/\303\234bersicht.md" | 17 +
.../integration/unicode/docs/\342\231\252.md" | 17 +
mkdocs/tests/integration/unicode/mkdocs.yml | 1 +
mkdocs/tests/nav_tests.py | 63 +++
mkdocs/tests/utils/ghp_import_tests.py | 29 ++
mkdocs/tests/utils/utils_tests.py | 34 +-
mkdocs/themes/mkdocs/base.html | 78 ++--
mkdocs/themes/mkdocs/content.html | 6 +-
mkdocs/themes/mkdocs/css/base.css | 108 ++++--
mkdocs/themes/mkdocs/css/highlight.css | 1 -
.../mkdocs/fonts/glyphicons-halflings-regular.eot | Bin 0 -> 20127 bytes
.../mkdocs/fonts/glyphicons-halflings-regular.svg | 288 ++++++++++++++
.../mkdocs/fonts/glyphicons-halflings-regular.ttf | Bin 0 -> 45404 bytes
.../mkdocs/fonts/glyphicons-halflings-regular.woff | Bin 0 -> 23424 bytes
.../fonts/glyphicons-halflings-regular.woff2 | Bin 0 -> 18028 bytes
mkdocs/themes/mkdocs/js/base.js | 20 +
mkdocs/themes/mkdocs/main.html | 10 +
mkdocs/themes/mkdocs/nav-sub.html | 12 +-
mkdocs/themes/mkdocs/nav.html | 63 +--
mkdocs/themes/mkdocs/search-modal.html | 24 ++
mkdocs/themes/mkdocs/toc.html | 8 +-
mkdocs/themes/readthedocs/base.html | 67 ++--
mkdocs/themes/readthedocs/breadcrumbs.html | 23 +-
mkdocs/themes/readthedocs/css/highlight.css | 1 -
mkdocs/themes/readthedocs/css/theme.css | 2 +-
mkdocs/themes/readthedocs/css/theme_extra.css | 92 +++--
mkdocs/themes/readthedocs/footer.html | 16 +-
mkdocs/themes/readthedocs/main.html | 10 +
mkdocs/themes/readthedocs/search.html | 4 +-
mkdocs/themes/readthedocs/toc.html | 4 +-
mkdocs/themes/readthedocs/versions.html | 16 +-
mkdocs/utils/__init__.py | 64 +++-
mkdocs/utils/filters.py | 6 +
mkdocs/utils/ghp_import.py | 19 +-
requirements/project-min.txt | 2 -
requirements/project.txt | 2 -
setup.py | 2 -
tox.ini | 22 +-
99 files changed, 3298 insertions(+), 731 deletions(-)
diff --git a/.codecov.yml b/.codecov.yml
new file mode 100644
index 0000000..36883d7
--- /dev/null
+++ b/.codecov.yml
@@ -0,0 +1,11 @@
+codecov:
+ ci:
+ - "!ci.appveyor.com"
+coverage:
+ status:
+ patch: false
+ project:
+ default:
+ target: 90
+
+comment: false
diff --git a/.csslintrc b/.csslintrc
new file mode 100644
index 0000000..76f68b0
--- /dev/null
+++ b/.csslintrc
@@ -0,0 +1,45 @@
+--exclude-list = mkdocs/themes/mkdocs/css/bootstrap-custom.min.css,
+ mkdocs/themes/readthedocs/css/bootstrap-custom.min.css,
+ mkdocs/themes/mkdocs/css/font-awesome-4.5.0.css,
+ mkdocs/themes/readthedocs/css/font-awesome-4.5.0.css,
+ mkdocs/themes/mkdocs/css/highlight.css,
+ mkdocs/themes/readthedocs/css/highlight.css,
+ mkdocs/themes/readthedocs/css/theme.css
+--errors = known-properties,
+ box-sizing,
+ outline-none,
+ bulletproof-font-face,
+ compatible-vendor-prefixes,
+ errors,
+ duplicate-background-images,
+ duplicate-properties,
+ empty-rules,
+ selector-max-approaching,
+ gradients,
+ floats,
+ font-faces,
+ font-sizes,
+ shorthand,
+ import,
+ import-ie-limit,
+ text-indent,
+ rules-count,
+ regex-selectors,
+ selector-max,
+ selector-newline,
+ star-property-hack,
+ underscore-property-hack,
+ universal-selector,
+ unqualified-attributes,
+ vendor-prefix,
+ zero-units,
+ overqualified-elements,
+ unique-headings,
+ qualified-headings,
+ ids,
+ display-property-grouping,
+ fallback-colors,
+ box-model,
+ important,
+ adjoining-classes
+--ignore = order-alphabetical
diff --git a/.jshintignore b/.jshintignore
new file mode 100644
index 0000000..6807d0c
--- /dev/null
+++ b/.jshintignore
@@ -0,0 +1,7 @@
+mkdocs/themes/**/js/highlight.pack.js
+mkdocs/themes/**/js/jquery-**.min.js
+mkdocs/themes/**/js/bootstrap-**.min.js
+mkdocs/themes/**/js/modernizr-**.min.js
+mkdocs/assets/search/mkdocs/js/require.js
+mkdocs/assets/search/mkdocs/js/mustache.min.js
+mkdocs/assets/search/mkdocs/js/lunr.min.js
diff --git a/.travis.yml b/.travis.yml
index d5f9640..ca419be 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -2,6 +2,11 @@ sudo: false
language: python
python: '3.5'
env:
+- TOXENV=flake8
+- TOXENV=markdown-lint
+- TOXENV=linkchecker
+- TOXENV=jshint
+- TOXENV=csslint
- TOXENV=py26-integration
- TOXENV=py26-min-req
- TOXENV=py26-unittests
@@ -23,18 +28,19 @@ env:
- TOXENV=pypy3-integration
- TOXENV=pypy3-min-req
- TOXENV=pypy3-unittests
-- TOXENV=flake8
-- TOXENV=markdown-lint
install:
- pip install tox
- gem install mdl
+- npm install -g jshint
+- npm install -g csslint
script:
- git clean -f -d -x
- tox
matrix:
- fast_finish: true
allow_failures:
- - env: TOXENV=markdown-lint
+ - env: TOXENV=pypy3-integration
+ - env: TOXENV=pypy3-min-req
+ - env: TOXENV=pypy3-unittests
before_install: pip install codecov
after_success: codecov
deploy:
diff --git a/MANIFEST.in b/MANIFEST.in
index a0a5a2b..caaaa0e 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,5 +1,5 @@
include README.md
-include LICENSE.md
-recursive-include mkdocs *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff *.xml *.mustache
+include LICENSE
+recursive-include mkdocs *.ico *.js *.css *.png *.html *.eot *.svg *.ttf *.woff *.woff2 *.xml *.mustache
recursive-exclude * __pycache__
recursive-exclude * *.py[co]
diff --git a/README.md b/README.md
index 3c34978..26a90ce 100644
--- a/README.md
+++ b/README.md
@@ -11,15 +11,17 @@ Project documentation with Markdown.
[![Coverage Status][codecov-image]][codecov-link]
[![Landscale Code Health][landscape-image]][landscape-link]
-## [See the MkDocs documentation: www.mkdocs.org][mkdocs]
+- View the [MkDocs documentation][mkdocs].
+- Project [release notes][release-notes].
+- Visit the [MkDocs wiki](https://github.com/mkdocs/mkdocs/wiki) for community
+ resources, including third party themes and a list of MkDocs users.
+- IRC channel: `#mkdocs` on freenode.
+- Discussions and support: <https://groups.google.com/forum/#!forum/mkdocs>
-Release notes: <http://www.mkdocs.org/about/release-notes/>
+## Code of Conduct
-Project roadmap: [https://github.com/mkdocs/mkdocs/wiki][roadmap]
-
-IRC channel: `#mkdocs` on freenode.
-
-Discussions and support: <https://groups.google.com/forum/#!forum/mkdocs>
+Everyone interacting in the MkDocs project's codebases, issue trackers, chat
+rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
[appveyor-image]: https://img.shields.io/appveyor/ci/d0ugal/mkdocs/master.png
[appveyor-link]: https://ci.appveyor.com/project/d0ugal/mkdocs
@@ -35,4 +37,6 @@ Discussions and support: <https://groups.google.com/forum/#!forum/mkdocs>
[travis-link]: https://travis-ci.org/mkdocs/mkdocs
[mkdocs]: http://www.mkdocs.org
-[roadmap]: https://github.com/mkdocs/mkdocs/wiki
+[release-notes]: http://www.mkdocs.org/about/release-notes/
+
+[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
diff --git a/docs/about/contributing.md b/docs/about/contributing.md
index 953b05c..5d4337e 100644
--- a/docs/about/contributing.md
+++ b/docs/about/contributing.md
@@ -10,6 +10,11 @@ ways, a few examples are:
- Documentation improvements
- Bug reports and patch reviews
+## Code of Conduct
+
+Everyone interacting in the MkDocs project's codebases, issue trackers, chat
+rooms, and mailing lists is expected to follow the [PyPA Code of Conduct].
+
## Reporting an Issue
Please include as much detail as you can. Let us know your platform and MkDocs
@@ -59,5 +64,6 @@ 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/
+[tox]: https://tox.readthedocs.io/en/latest/
[travis]: https://travis-ci.org/repositories
+[PyPA Code of Conduct]: https://www.pypa.io/en/latest/code-of-conduct/
diff --git a/docs/about/license.md b/docs/about/license.md
index a41499f..44546d3 100644
--- a/docs/about/license.md
+++ b/docs/about/license.md
@@ -6,13 +6,9 @@ The legal stuff.
## Included projects
-Themes used under license from the Bootstrap, ReadTheDocs, GhostWriter and
-Bootswatch projects.
+Themes used under license from the ReadTheDocs projects.
-* Bootstrap theme - [View license](//github.com/twbs/bootstrap/blob/master/LICENSE).
-* ReadTheDocs theme - [View license](//github.com/snide/sphinx_rtd_theme/blob/master/LICENSE).
-* 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).
+* ReadTheDocs theme - [View license](https://github.com/snide/sphinx_rtd_theme/blob/master/LICENSE).
Many thanks to the authors and contributors of those wonderful projects.
diff --git a/docs/about/release-notes.md b/docs/about/release-notes.md
index 84f47c9..ea3550f 100644
--- a/docs/about/release-notes.md
+++ b/docs/about/release-notes.md
@@ -13,6 +13,223 @@ You can determine your currently installed version using `mkdocs --version`:
$ mkdocs --version
mkdocs, version 0.15.2
+## Maintenance team
+
+The current and past members of the MkDocs team.
+
+* [@tomchristie](https://github.com/tomchristie/)
+* [@d0ugal](https://github.com/d0ugal/)
+* [@waylan](https://github.com/waylan/)
+
+## Version 0.16.1 (2016-12-22)
+
+* Ensure scrollspy behavior does not affect nav bar (#1094)
+* Only "load" a theme when it is explicitly requested by the user (#1105)
+
+## Version 0.16 (2016-11-04)
+
+### Major Additions to Version 0.16.0
+
+#### Template variables refactored. (#874)
+
+##### Page Context
+
+Page specific variable names in the template context have been refactored as
+defined in [Custom Themes](../user-guide/custom-themes/#page). The
+old variable names will issue a warning but continue to work for version 0.16,
+but may be removed in a future version.
+
+Any of the following old page variables should be updated to the new ones in
+user created and third-party templates:
+
+| Old Variable Name | New Variable Name |
+| ----------------- | ------------------- |
+| current_page | [page] |
+| page_title | [page.title] |
+| content | [page.content] |
+| toc | [page.toc] |
+| meta | [page.meta] |
+| canonical_url | [page.canonical_url]|
+| previous_page | [page.previous_page]|
+| next_page | [page.next_page] |
+
+[page]: ../user-guide/custom-themes/#page
+[page.title]: ../user-guide/custom-themes/#pagetitle
+[page.content]: ../user-guide/custom-themes/#pagecontent
+[page.toc]: ../user-guide/custom-themes/#pagetoc
+[page.meta]: ../user-guide/custom-themes/#pagemeta
+[page.canonical_url]: ../user-guide/custom-themes/#pagecanonical_url
+[page.previous_page]: ../user-guide/custom-themes/#pageprevious_page
+[page.next_page]: ../user-guide/custom-themes/#pagenext_page
+
+##### Global Context
+
+Additionally, a number of global variables have been altered and/or deprecated
+and user created and third-party templates should be updated as outlined below:
+
+Previously, the global variable `include_nav` was altered programmatically based
+on the number of pages in the nav. The variable will issue a warning but
+continue to work for version 0.16, but may be removed in a future version. Use
+`{% if nav|length>1 %}` instead.
+
+Previously, the global variable `include_next_prev` was altered programmatically
+based on the number of pages in the nav. The variable will issue a warning but
+continue to work for version 0.16, but may be removed in a future version. Use
+`{% if page.next_page or page.previous_page %}` instead.
+
+Previously the global variable `page_description` was altered programmatically
+based on whether the current page was the homepage. Now it simply maps to
+`config['site_description']`. Use `{% if page.is_homepage %}` in the template to
+conditionally change the description.
+
+The global variable `homepage_url` maps directly to `nav.homepage.url` and is
+being deprecated. The variable will issue a warning but continue to work for
+version 0.16, but may be removed in a future version. Use `nav.homepage.url`
+instead.
+
+The global variable `favicon` maps to the configuration setting `site_favicon`.
+Both the template variable and the configuration setting are being deprecated
+and will issue a warning but continue to work for version 0.16, and may be
+removed in a future version. Use `{{ base_url }}/img/favicon.ico` in your
+template instead. Users can simply save a copy of their custom favicon icon to
+`img/favicon.ico` in either their `docs_dir` or `theme_dir`.
+
+A number of variables map directly to similarly named variables in the `config`.
+Those variables are being deprecated and will issue a warning but continue to
+work for version 0.16, but may be removed in a future version. Use
+`config.var_name` instead, where `var_name` is the name of one of the
+[configuration] variables.
+
+[configuration]: /user-guide/configuration.md
+
+Below is a summary of all of the changes made to the global context:
+
+| Old Variable Name | New Variable Name or Expression |
+| ----------------- | -------------------------------------- |
+| current_page | page |
+| include_nav | nav|length>1 |
+| include_next_prev | (page.next_page or page.previous_page) |
+| site_name | config.site_name |
+| site_author | config.site_author |
+| page_description | config.site_description |
+| repo_url | config.repo_url |
+| repo_name | config.repo_name |
+| site_url | config.site_url |
+| copyright | config.copyright |
+| google_analytics | config.google_analytics |
+| homepage_url | nav.homepage.url |
+| favicon | {{ base_url }}/img/favicon.ico |
+
+#### Increased Template Customization. (#607)
+
+The built-in themes have been updated by having each of their many parts wrapped
+in template blocks which allow each individual block to be easily overridden
+using the `theme_dir` config setting. Without any new settings, you can use a
+different analytics service, replace the default search function, or alter the
+behavior of the navigation, among other things. See the relevant
+[documentation][blocks] for more details.
+
+To enable this feature, the primary entry point for page templates has been
+changed from `base.html` to `main.html`. This allows `base.html` to continue to
+exist while allowing users to override `main.html` and extend `base.html`. For
+version 0.16, `base.html` will continue to work if no `main.html` template
+exists, but it is deprecated and will raise a warning. In version 1.0, a build
+will fail if no `main.html` template exists. Any custom and third party
+templates should be updated accordingly.
+
+The easiest way for a third party theme to be updated would be to simply add a
+`main.html` file which only contains the following line:
+
+```django
+{% extends "base.html" %}
+```
+
+That way, the theme contains the `main.html` entry point, and also supports
+overriding blocks in the same manner as the built-in themes. Third party themes
+are encouraged to wrap the various pieces of their templates in blocks in order
+to support such customization.
+
+[blocks]: ../user-guide/styling-your-docs/#overriding-template-blocks
+
+#### Auto-Populated `extra_css` and `extra_javascript` Deprecated. (#986)
+
+In previous versions of MkDocs, if the `extra_css` or `extra_javascript` config
+settings were empty, MkDocs would scan the `docs_dir` and auto-populate each
+setting with all of the CSS and JavaScript files found. This behavior is
+deprecated and a warning will be issued. In the next release, the auto-populate
+feature will stop working and any unlisted CSS and JavaScript files will not be
+included in the HTML templates. In other words, they will still be copied to the
+`site-dir`, but they will not have any effect on the theme if they are not
+explicitly listed.
+
+All CSS and javaScript files in the `docs_dir` should be explicitly listed in
+the `extra_css` or `extra_javascript` config settings going forward.
+
+#### Support for dirty builds. (#990)
+
+For large sites the build time required to create the pages can become problematic,
+thus a "dirty" build mode was created. This mode simply compares the modified time
+of the generated HTML and source markdown. If the markdown has changed since the
+HTML then the page is re-constructed. Otherwise, the page remains as is. This mode
+may be invoked in both the `mkdocs serve` and `mkdocs build` commands:
+
+```text
+mkdocs serve --dirtyreload
+```
+
+```text
+mkdocs build --dirty
+```
+
+It is important to note that this method for building the pages is for development
+of content only, since the navigation and other links do not get updated on other
+pages.
+
+#### Stricter Directory Validation
+
+Previously, a warning was issued if the `site_dir` was a child directory of the
+`docs_dir`. This now raises an error. Additionally, an error is now raised if
+the `docs_dir` is set to the directory which contains your config file rather
+than a child directory. You will need to rearrange you directory structure to
+better conform with the documented [layout].
+
+[layout]: ../user-guide/writing-your-docs/#file-layout
+
+### Other Changes and Additions to Version 0.16.0
+
+* Bugfix: Support `gh-deploy` command on Windows with Python 3 (#722)
+* Bugfix: Include .woff2 font files in Python package build (#894)
+* Various updates and improvements to Documentation Home Page/Tutorial (#870)
+* Bugfix: Support livereload for config file changes (#735)
+* Bugfix: Non-media template files are no longer copied with media files (#807)
+* Add a flag (-e/--theme-dir) to specify theme directory with the commands
+ `mkdocs build` and `mkdocs serve` (#832)
+* Fixed issues with Unicode file names under Windows and Python 2. (#833)
+* Improved the styling of in-line code in the MkDocs theme. (#718)
+* Bugfix: convert variables to JSON when being passed to JavaScript (#850)
+* Updated the ReadTheDocs theme to match the upstream font sizes and colors
+ more closely. (#857)
+* Fixes an issue with permalink markers showing when the mouse was far above
+ them (#843)
+* Bugfix: Handle periods in directory name when automatically creating the
+ pages config. (#728)
+* Update searching to Lunr 0.7, which comes with some performance enhancements
+ for larger documents (#859)
+* Bugfix: Support SOURCE_DATE_EPOCH environment variable for "reproducible"
+ builds (#938)
+* Follow links when copying media files (#869).
+* Change "Edit on..." links to point directly to the file in the source
+ repository, rather than to the root of the repository (#975), configurable
+ via the new [`edit_uri`](../user-guide/configuration.md#edit_uri) setting.
+* Bugfix: Don't override config value for strict mode if not specified on CLI
+ (#738).
+* Add a `--force` flag to the `gh-deploy` command to force the push to the
+ repository (#973).
+* Improve alignment for current selected menu item in readthedocs theme (#888).
+* `http://user.github.io/repo` => `https://user.github.io/repo/` (#1029).
+* Improve installation instructions (#1028).
+* Account for wide tables and consistently wrap inline code spans (#834).
+* Bugfix: Use absolute URLs in nav & media links from error templates (#77).
## Version 0.15.3 (2016-02-18)
@@ -46,7 +263,7 @@ details about these specific themes.
[MkDocs Bootstrap]: http://mkdocs.github.io/mkdocs-bootstrap/
[MkDocs Bootswatch]: http://mkdocs.github.io/mkdocs-bootswatch/
-They will be included with MkDocs by default until the 1.0 release. After that
+They will be included with MkDocs by default until a future release. After that
they will be installable with pip: `pip install mkdocs-bootstrap` and `pip
install mkdocs-bootswatch`
diff --git a/docs/img/initial-config.png b/docs/img/initial-config.png
deleted file mode 100644
index 8142d30..0000000
Binary files a/docs/img/initial-config.png and /dev/null differ
diff --git a/docs/img/multipage.png b/docs/img/multipage.png
new file mode 100644
index 0000000..906fa8f
Binary files /dev/null and b/docs/img/multipage.png differ
diff --git a/docs/img/readthedocs.png b/docs/img/readthedocs.png
index 4c20718..ffad9f7 100644
Binary files a/docs/img/readthedocs.png and b/docs/img/readthedocs.png differ
diff --git a/docs/img/screenshot.png b/docs/img/screenshot.png
index dd7a239..95f3176 100644
Binary files a/docs/img/screenshot.png and b/docs/img/screenshot.png differ
diff --git a/docs/img/search.png b/docs/img/search.png
new file mode 100644
index 0000000..91ed676
Binary files /dev/null and b/docs/img/search.png differ
diff --git a/docs/img/site-name.png b/docs/img/site-name.png
index 7b07541..82f38a3 100644
Binary files a/docs/img/site-name.png and b/docs/img/site-name.png differ
diff --git a/docs/img/win-py-install.png b/docs/img/win-py-install.png
new file mode 100644
index 0000000..88d0a45
Binary files /dev/null and b/docs/img/win-py-install.png differ
diff --git a/docs/index.md b/docs/index.md
index 8951157..61c77aa 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -13,19 +13,20 @@ configuration file.
### Host anywhere
-Builds completely static HTML sites that you can host on GitHub pages, Amazon
-S3, or anywhere else you choose.
+MkDocs builds completely static HTML sites that you can host on GitHub pages,
+Amazon S3, or [anywhere][deploy] else you choose.
### Great themes available
-There's a stack of good looking themes included by default. Choose from
-bootstrap, readthedocs, or any of the 12 bootswatch themes.
+There's a stack of good looking themes available for MkDocs. Choose between
+the built in themes: [mkdocs] and [readthedocs], select one of the 3rd
+party themes in the [MkDocs wiki], or [build your own].
### Preview your site as you work
-The built-in devserver allows you to preview your documentation as you're
-writing it. It will even auto-reload whenever you save any changes, so all you
-need to do to see your latest edits is refresh your browser.
+The built-in dev-server allows you to preview your documentation as you're
+writing it. It will even auto-reload and refresh your browser whenever you save
+your changes.
### Easy to customize
@@ -36,9 +37,29 @@ the theme.
## Installation
-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:
+### Install with a Package Manager
+
+If you have and use a package manager (such as [apt-get], [dnf], [homebrew],
+[yum], [chocolatey], etc.) to install packages on your system, then you may
+want to search for a "MkDocs" package and, if a recent version is available,
+install it with your package manager (check your system's documentation for
+details). That's it, you're done! Skip down to [Getting Started](#getting-started).
+
+If your package manager does not have a recent "MkDocs" package, you can still
+use your package manager to install "Python" and "pip". Then you can use pip to
+[install MkDocs](#installing-mkdocs).
+
+[apt-get]: https://help.ubuntu.com/community/AptGet/Howto
+[homebrew]: http://brew.sh/
+[dnf]: http://dnf.readthedocs.io/en/latest/index.html
+[yum]: http://yum.baseurl.org/
+[chocolatey]: https://chocolatey.org/
+
+### Manual Installation
+
+In order to manually 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 from the command line:
```bash
$ python --version
@@ -47,9 +68,41 @@ $ pip --version
pip 1.5.2
```
-MkDocs supports Python 2.6, 2.7, 3.3 and 3.4.
+MkDocs supports Python versions 2.6, 2.7, 3.3, 3.4, 3.5 and pypy.
+
+#### Installing Python
+
+Install [Python] by downloading an installer appropriate for your system from
+[python.org] and running it.
+
+!!! Note
+
+ If you are installing Python on Windows, be sure to check the box to have
+ Python added to your PATH if the installer offers such an option (it's
+ normally off by default).
+
+ 
+
+[python.org]: https://www.python.org/downloads/
+
+#### Installing pip
+
+If you're using a recent version of Python, the Python package manager, [pip],
+is most likely installed by default. However, you may need to upgrade pip to the
+lasted version:
+
+```bash
+pip install --upgrade pip
+```
+
+If you need to install [pip] for the first time, download [get-pip.py].
+Then run the following command to install it:
-On Windows we recommend that you install Python and pip with [Chocolatey].
+```bash
+python get-pip.py
+```
+
+#### Installing MkDocs
Install the `mkdocs` package using pip:
@@ -62,12 +115,32 @@ You should now have the `mkdocs` command installed on your system. Run `mkdocs
```bash
$ mkdocs --version
-mkdocs, version 0.15.2
+mkdocs, version 0.15.3
```
+!!! Note
+ If you are using Windows, some of the above commands may not work
+ out-of-the-box.
+
+ A quick solution may be to preface every Python command with `python -m`
+ like this:
+
+ python -m pip install mkdocs
+ python -m mkdocs
+
+ For a more permanent solution, you may need to edit your `PATH` environment
+ variable to include the `Scripts` directory of your Python installation.
+ Recent versions of Python include a script to do this for you. Navigate to
+ your Python installation directory (for example `C:\Python34\`), open the
+ `Tools`, then `Scripts` folder, and run the `win_add2path.py` file by double
+ clicking on it. Alternatively, you can [download][a2p] the script and run it
+ (`python win_add2path.py`).
+
+[a2p]: https://svn.python.org/projects/python/trunk/Tools/scripts/win_add2path.py
+
---
-## Getting started
+## Getting Started
Getting started is super easy.
@@ -76,109 +149,136 @@ mkdocs new my-project
cd my-project
```
-Let's take a moment to review the initial project that's been created for us.
+Take a moment to review the initial project that has been created for you.
There's a single configuration file named `mkdocs.yml`, and a folder named
-`docs` that will contain our documentation source files. Right now the `docs`
+`docs` that will contain your documentation source files. Right now the `docs`
folder just contains a single documentation page, named `index.md`.
-MkDocs comes with a built-in webserver that lets you preview your documentation
-as you work on it. We start the webserver by making sure we're in the same
-directory as the `mkdocs.yml` config file, and then running the `mkdocs serve`
+MkDocs comes with a built-in dev-server that lets you preview your documentation
+as you work on it. Make sure you're in the same directory as the `mkdocs.yml`
+configuration file, and then start the server by running the `mkdocs serve`
command:
```bash
$ mkdocs serve
-Running at: http://127.0.0.1:8000/
+INFO - Building documentation...
+INFO - Cleaning site directory
+[I 160402 15:50:43 server:271] Serving on http://127.0.0.1:8000
+[I 160402 15:50:43 handlers:58] Start watching changes
+[I 160402 15:50:43 handlers:60] Start detecting changes
```
-Open up [http://127.0.0.1:8000/](http://127.0.0.1:8000/) in your browser, and
-you'll see the index page being displayed:
+Open up `http://127.0.0.1:8000/` in your browser, and you'll see the default
+home page being displayed:
-The webserver also supports auto-reloading, and will rebuild your documentation
-whenever anything in the configuration file, documentation directory or theme
+The dev-server also supports auto-reloading, and will rebuild your documentation
+whenever anything in the configuration file, documentation directory, or theme
directory changes.
-Go ahead and edit the `docs/index.md` file now and save the file. Then simply
-hit reload in the browser and you'll see your updated documentation.
+Open the `docs/index.md` document in your text editor of choice, change the
+initial heading to `MkLorum`, and save your changes. Your browser will
+auto-reload and you should see your updated documentation immediately.
-Now's also a good time to edit the configuration file, `mkdocs.yml`. Change the
-`site_name` setting to something else and save the file.
+Now try editing the configuration file: `mkdocs.yml`. Change the
+[`site_name`][site_name] setting to `MkLorum` and save the file.
-
+```yaml
+site_name: MkLorum
+```
-Once you hit reload in the browser you'll see your new site name take effect.
+Your browser should immediately reload, and you'll see your new site name take
+effect.
## Adding pages
-Go ahead and edit the `docs/index.md` document, and change the initial heading to
-`MkLorum`, then reload the site in your browser, and you should see the change
-take effect immediately.
-
-Let's also add a second page to our documentation:
+Now add a second page to your documentation:
```bash
-curl 'jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
+curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md
```
-We'd like our documentation site to include some navigation headers, so we'll
-edit the configuration file and add some information about the order and title
-to use for out headers:
+As our documentation site will include some navigation headers, you may want to
+edit the configuration file and add some information about the order, title, and
+nesting of each page in the navigation header by adding a [`pages`][pages]
+setting:
-```no-highlight
+```yaml
site_name: MkLorum
pages:
-- Home: index.md
-- About: about.md
+ - Home: index.md
+ - About: about.md
```
-Refresh the browser and you'll now see a navigation bar with `Home` and `About`
-headers.
+Save your changes and you'll now see a navigation bar with `Home` and `About`
+items on the left as well as `Search`, `Previous`, and `Next` items on the
+right.
+
+
+
+Try the menu items and navigate back and forth between pages. Then click on
+`Search`. A search dialog will appear, allowing you to search for any text on
+any page. Notice that the search results include every occurrence of the search
+term on the site and links directly to the section of the page in which the
+search term appears. You get of all that with no effort or configuration on your
+part!
+
+
## Theming our documentation
-While we're here can also change the configuration file to alter how the
-documentation is displayed. Let's go ahead and change the theme. Edit the
-`mkdocs.yml` file to the following:
+Now change the configuration file to alter how the documentation is displayed by
+changing the theme. Edit the `mkdocs.yml` file and add a [`theme`][theme] setting:
-```no-highlight
+```yaml
site_name: MkLorum
pages:
-- Home: index.md
-- About: about.md
+ - Home: index.md
+ - About: about.md
theme: readthedocs
```
-Refresh the browser again, and you'll now see the ReadTheDocs theme being used.
+Save your changes, and you'll see the ReadTheDocs theme being used.
+## Changing the Favicon Icon
+
+By default, MkDocs uses the [MkDocs favicon] icon. To use a different icon, create
+an `img` subdirectory in your `docs_dir` and copy your custom `favicon.ico` file
+to that directory. MkDocs will automaticaly detect and use that file as your
+favicon icon.
+
+[MkDocs favicon]: /img/favicon.ico
+
## Building the site
-That's looking good. We're ready to deploy the first pass of our `MkLorum`
-documentation now. Let's build the documentation.
+That's looking good. You're ready to deploy the first pass of your `MkLorum`
+documentation. First build the documentation:
```bash
mkdocs build
```
-This will create a new directory, named `site`. Let's take a look inside the
+This will create a new directory, named `site`. Take a look inside the
directory:
```bash
-ls site
-about css fonts img index.html js
+$ ls site
+about fonts index.html license search.html
+css img js mkdocs sitemap.xml
```
-Notice that our source documentation has been output as two HTML files named
-`index.html` and `about/index.html`. We also have various other media that's
-been copied into the `site` directory as part of the documentation theme.
+Notice that your source documentation has been output as two HTML files named
+`index.html` and `about/index.html`. You also have various other media that's
+been copied into the `site` directory as part of the documentation theme. You
+even have a `sitemap.xml` file and `mkdocs/search_index.json`.
If you're using source code control such as `git` you probably don't want to
check your documentation builds into the repository. Add a line containing
@@ -188,11 +288,11 @@ check your documentation builds into the repository. Add a line containing
echo "site/" >> .gitignore
```
-If you're using another source code control you'll want to check it's
+If you're using another source code control tool you'll want to check it's
documentation on how to ignore specific directories.
After some time, files may be removed from the documentation but they will still
-reside in the `site` directory. To remove those stale files, just run mkdocs
+reside in the `site` directory. To remove those stale files, just run `mkdocs`
with the `--clean` switch.
```bash
@@ -218,22 +318,30 @@ mkdocs build --help
## Deploying
-The documentation site that we've just built only uses static files so you'll be
+The documentation site that you 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.
+S3] may be good hosting options, depending upon your needs. Upload the contents
+of the entire `site` directory to wherever you're hosting your website from and
+you're done. For specific instructions on a number of common hosts, see the
+[Deploying your Docs][deploy] page.
## Getting help
To get help with MkDocs, please use the [discussion group], [GitHub issues] or
the MkDocs IRC channel `#mkdocs` on freenode.
+[deploy]: user-guide/deploying-your-docs/
+[mkdocs]: user-guide/styling-your-docs/#mkdocs
+[readthedocs]: user-guide/styling-your-docs/#readthedocs
+[MkDocs wiki]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
+[build your own]: user-guide/custom-themes/
[Amazon S3]: http://docs.aws.amazon.com/AmazonS3/latest/dev/WebsiteHosting.html
-[Chocolatey]: https://chocolatey.org/
+[get-pip.py]: https://bootstrap.pypa.io/get-pip.py
+[pages]: user-guide/configuration/#pages
[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
+[GitHub project pages]: https://help.github.com/articles/creating-project-pages-manually/
+[pip]: http://pip.readthedocs.io/en/stable/installing/
[Python]: https://www.python.org/
-[Deploying your Docs]: user-guide/deploying-your-docs.md
+[site_name]: user-guide/configuration/#site_name
+[theme]: user-guide/configuration/#theme
\ No newline at end of file
diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md
index 95fb780..76652fe 100644
--- a/docs/user-guide/configuration.md
+++ b/docs/user-guide/configuration.md
@@ -50,6 +50,44 @@ 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`
+### edit_uri
+
+Path from the base `repo_url` to the docs directory when directly viewing a
+page, accounting for specifics of the repository host (e.g. GitHub, Bitbucket,
+etc), the branch, and the docs directory itself. Mkdocs concatenates `repo_url`
+and `edit_uri`, and appends the input path of the page.
+
+When set, provides a link directly to the page in your source repository. This
+makes it easier to find and edit the source for the page. If `repo_url` is not
+set, this option is ignored.
+
+For example, for a GitHub-hosted repository, the `edit_uri` would be as follows.
+(Note the `edit` path and `master` branch...)
+
+```yaml
+edit_uri: edit/master/docs/
+```
+
+For a Bitbucket-hosted repository, the equivalent `edit_uri` would be as
+follows. (Note the `src` path and `default` branch...)
+
+```yaml
+edit_uri: src/default/docs/
+```
+
+For other repository hosts, `edit_uri` works the same way. Simply specify the
+relative path to the docs directory.
+
+**default**: `edit/master/docs/` or `src/default/docs/` for GitHub or Bitbucket
... 5535 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