It now better reflects the new pages configuration format. The pages section
in `configuration.md` was also reduced to a summary, with most of the
details now in `writing-your-docs.md`. Also fixed a few typos.
-Reorganize the yaml loading function to make it more clear what is
happening.
-Comment more to to make explicitly clear what is happening.
-Remove unnecessary 'pass'
-Make a note that 'finally' should be removed when the root of the issue
is cleared up.
-Update release notes with info on change.
The --quiet and --verbose options can be called from any command (parent or
subcommands), yet they are only defined once. Code adapted from:
https://github.com/mitsuhiko/click/issues/108#issuecomment-44691173
If either or both options are defined more than once by the user, the last
option defined is the only one which controls.
No support of -vvv to increase verbosity. MkDocks only utilizes a few
loging levels so the additional control offers no real value. Can always
be added later.
Updated release notes.
Config validation now handles all extension processing:
* Builtin extensions are defined and within the default scheme.
* User extensions are defined only as a list in the config. Note, this is
a backward incompatable change from the previous (short-lived) release.
* The users extensions are added to the list of builtins.
* Any duplicates are accounted for in validation.
* Extension options are supported by a child key/value pair on the ext name.
* All extension options are compiled into a format Markdown accepts
within the validation process and are saved to the internal `mdx_configs`
config setting.
* The `mdx_configs` setting is private and raises an error if set by the user.
* A whole suite of tests were added to test all aspects of ext validation.
All relevant build tests were updated to pass the config to
`build.convert_markdown` as the config now handles all extension data.
The relevant documentation was updated to reflect the changes. While I was
at it, I spellchecked the entire document and made a few additional formatting
changes.
This fixes#519 plus a lot more.
This change adds a new configuration option called `extra` which allows
uers to add an arbitrary set of data to the config that is passed to the
template context.
Fixes#144
The current pages configuration looks like this:
pages:
- ['index.md', 'Home']
- ['writing-your-docs.md', 'User Guide', 'Writing your docs']
- ['styling-your-docs.md', 'User Guide', 'Styling your docs']
- ['configuration.md', 'User Guide', 'Configuration']
- ['about/license.md', 'About', 'License']
- ['about/release-notes.md', 'About', 'Release Notes']
- ['about/contributing.md', 'About', 'Contributing']
This has a number of flaws:
- It isn't clear how to add second levels of navigation for
newcomers. This is often queried and not easy to document.
- We are representing a tree structure as a set of flat items
that need to be merged. This creates some interesting edge
cases, for example:
- ['writing-your-docs.md', 'User Guide']
- ['styling-your-docs.md', 'User Guide', 'Styling your docs']
Is the first entry a page with the title User Guide? or a page
in the User Guide category with an automatic title.
- We are currently limited to two levels deep in the navigation.
Changing this with the current structure isn't trivial.
This change adds a new format which makes the above configuration
look like this:
pages:
- Home: index.md
- User Guide:
- user-guide/writing-your-docs.md
- user-guide/styling-your-docs.md
- user-guide/configuration.md
- About:
- License: about/license.md
- about/release-notes.md
- Contributing: about/contributing.md
With this structure, we can more easily see the documentation
tree and it is far more obvious what the navigation will look
like. It also removes the ambiguous edge cases and opens up the
possibility of adding further levels to the navigation more
easily.
This change restructures the pages configuration, but doesn't yet
allow users to add further levels in the navigation.
Fixes#6
