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
This is similar to extra_css and extra_javascript except it picks up
HTML and XML files and runs them through jinja2 with the global context.
This adds for quite a bit of flexability and allows people to easily add
custom site maps, static and templates htlp.
Fixes#28Fixes#44
This reimplements the CLI interface to use Click, which in turn gives us
a much easier to use interface as it provides help messages for all the
commands and individual commands.
Fixes#259
Python Markdown inclusion order can be important when including various
custom extensions. Conflicts can arise as to where extensions get
inserted in the workflow. By preserving order of how extensions are
defined in the settings file, this can allow a user to control
insertion order and work around these issues. As Py26 supported is
noted to be removed in the future, I saw no reason to add additional
dependencies for OrderedDict. Try catch statements can be removed when
Py26 support is removed.
