From 8dc0777813630a4e2046312d18b4427bcff27120 Mon Sep 17 00:00:00 2001 From: Tom Christie Date: Wed, 29 Jan 2014 16:46:10 +0000 Subject: [PATCH] local_file_urls -> use_directory_urls --- docs/user-guide/configuration.md | 69 +++++++++++++++++++++++--------- mkdocs.yml | 3 +- mkdocs/config.py | 2 +- mkdocs/nav.py | 8 ++-- mkdocs/utils.py | 6 +-- 5 files changed, 61 insertions(+), 27 deletions(-) diff --git a/docs/user-guide/configuration.md b/docs/user-guide/configuration.md index f3f1abc4..ca10c25b 100644 --- a/docs/user-guide/configuration.md +++ b/docs/user-guide/configuration.md @@ -4,68 +4,97 @@ Guide to all available configuration settings. --- +## Introduction + +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` and `pages` settings. All other settings are optional. + ## Required settings -#### project_title +#### site_name -Mea dicta aliquid ornatus cu, duis sanctus disputationi his in. Rebum adolescens definiebas vis te. Ornatus noluisse mel te, modo utinam ea sit, putent omittantur quo ad. Ius ad dicta iusto, vel ne nonumy quaestio. +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 + +When rendering the theme this setting will be passed as the `site_name` context variable. #### pages -Eam no quis bonorum legendos. Eos prodesset cotidieque in, atqui saperet eos te. Sit eruditi fastidii detraxit cu, sed elit voluptatum in. Vel esse possim accumsan et, eam et amet nihil putent. Mei putent impetus no, iuvaret labores duo an. +This is a **required setting**, and is used to determine the set of pages that should be built for the documentation. - pages: - - 'index.md' +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. -Quo ex ceteros theophrastus, mel eius repudiandae an, has autem legendos ut. Eu quo moderatius interpretaris, pro ad homero tractatos cotidieque. +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'] -Mea dicta aliquid ornatus cu, duis sanctus disputationi his in. Rebum adolescens definiebas vis te. Ornatus noluisse mel te, modo utinam ea sit, putent omittantur quo ad. Ius ad dicta iusto, vel ne nonumy quaestio. +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: pages: - ['index.md', 'Introduction'] - - ['user-guide/markdown.md', 'User Guide / Writing your documentation'] - - ['user-guide/themes.md', 'User Guide / Theming your documentation'] - - ['user-guide/configuration.md', 'User Guide / Configuration options'] + - ['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', 'Configuration Mashmallow'] + - ['about/license.md', 'About', 'License'] ## Project metadata -#### project_description +#### site_description Eam no quis bonorum legendos. Eos prodesset cotidieque in, atqui saperet eos te. Sit eruditi fastidii detraxit cu, sed elit voluptatum in. Vel esse possim accumsan et, eam et amet nihil putent. Mei putent impetus no, iuvaret labores duo an. -#### project_url +**default**: `null` + +#### site_url Quo ex ceteros theophrastus, mel eius repudiandae an, has autem legendos ut. Eu quo moderatius interpretaris, pro ad homero tractatos cotidieque. His errem dictas instructior ad, tation causae ceteros ex eum. Nam falli dicunt te, mea et unum contentiones, ius noluisse rationibus cotidieque ei. -#### project_favicon +**default**: `null` + +#### site_favicon Sit eruditi fastidii detraxit cu, sed elit voluptatum in. Vel esse possim accumsan et, eam et amet nihil putent. -#### project_author +**default**: `null` + +#### site_author Sit eruditi fastidii detraxit cu, sed elit voluptatum in. Vel esse possim accumsan et, eam et amet nihil putent. +**default**: `null` + ## Build directories #### theme Mea dicta aliquid ornatus cu, duis sanctus disputationi his in. Rebum adolescens definiebas vis te. Ornatus noluisse mel te, modo utinam ea sit, putent omittantur quo ad. Ius ad dicta iusto, vel ne nonumy quaestio. +**default**: `'bootstrap'` + #### theme_dir Eam no quis bonorum legendos. Eos prodesset cotidieque in, atqui saperet eos te. Sit eruditi fastidii detraxit cu, sed elit voluptatum in. Vel esse possim accumsan et, eam et amet nihil putent. Mei putent impetus no, iuvaret labores duo an. +**default**: `null` + #### docs_dir Quo ex ceteros theophrastus, mel eius repudiandae an, has autem legendos ut. Eu quo moderatius interpretaris, pro ad homero tractatos cotidieque. His errem dictas instructior ad, tation causae ceteros ex eum. Nam falli dicunt te, mea et unum contentiones, ius noluisse rationibus cotidieque ei. -#### build_dir +**default**: `'docs'` -Lorem ipsum dolor sit amet, eam facer liberavisse ad. Vis te cetero blandit temporibus, id meliore definiebas qui. At mei vidit etiam adipisci, mea ad malis nobis. An sed aeque munere facilisi, modus tractatos quo ei. Eu veniam tincidunt cum. +#### site_dir + +Consul percipitur usu an, no dico facer inermis cum. Eum ea mentitum accommodare. An sea periculis euripidis, dicant minimum patrioque at vis. Justo atomorum abhorreant vel in. Eos agam intellegam disputando at, zril consul nostrud ut eum. + +**default**: `'site'` ## Extra build steps @@ -83,14 +112,18 @@ Consul percipitur usu an, no dico facer inermis cum. Eum ea mentitum accommodare ## Preview controls -#### local_build +#### use_directory_urls Sit discere dolorem cu. Has an alienum repudiare delicatissimi. Cu salutatus efficiendi mea, in homero possim maiorum sed. Dicam delenit laboramus ad eum, altera laboramus instructior nec in. Vix et diam libris, eu sit justo soluta fuisset. Periculis maluisset eum ut, ut eos illud scaevola. -#### devserver_addr +**default**: `true` + +#### dev_addr Brute invidunt et qui. Ei mea epicuri placerat sententiae, at mea delicata hendrerit, suas legimus his id. Mel viderer commune molestiae at, quo ex similique argumentum. Sea ut doming graecis hendrerit, iriure praesent usu at. Eam purto petentium ne. Case ubique usu eu, no vidit quidam possit pri. +**default**: `'127.0.0.1:8000'` + ## Other configuration Vel at magna falli fierent. Clita putant nam no, cu per eros possit omnium, dicit pertinacia consetetur at has. Nam quis delenit cu, at vix consul expetendis, mucius mediocrem reprimique te mel. Ex vim quem oratio cotidieque, periculis iracundia at his, his omnium consulatu ei. diff --git a/mkdocs.yml b/mkdocs.yml index a0d0af96..bb1c8afb 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -5,4 +5,5 @@ pages: - ['user-guide/styling-your-docs.md', 'User Guide / Styling your docs'] - ['user-guide/configuration.md', 'User Guide / Configuration'] - ['about/license.md', 'About / License'] -theme_dir: 'theme' +#theme_dir: 'theme' +theme: 'cerulean' diff --git a/mkdocs/config.py b/mkdocs/config.py index def5773e..d3cb8d2a 100644 --- a/mkdocs/config.py +++ b/mkdocs/config.py @@ -15,7 +15,7 @@ DEFAULT_CONFIG = { 'theme_dir': None, 'dev_addr': '127.0.0.1:8000', - 'local_files': False + 'use_direcory_urls': True } diff --git a/mkdocs/nav.py b/mkdocs/nav.py index 847334aa..6659f9bc 100644 --- a/mkdocs/nav.py +++ b/mkdocs/nav.py @@ -11,10 +11,10 @@ import posixpath class SiteNavigation(object): - def __init__(self, pages_config, local_file_urls=False): + def __init__(self, pages_config, use_directory_urls=True): self.url_context = URLContext() self.nav_items, self.pages = \ - _generate_site_navigation(pages_config, self.url_context, local_file_urls) + _generate_site_navigation(pages_config, self.url_context, use_directory_urls) self.homepage = self.pages[0] if self.pages else None def __str__(self): @@ -106,7 +106,7 @@ class Header(object): return ret -def _generate_site_navigation(pages_config, url_context, local_file_urls=False): +def _generate_site_navigation(pages_config, url_context, use_directory_urls=True): """ Returns a list of Page and Header instances that represent the top level site navigation. @@ -116,7 +116,7 @@ def _generate_site_navigation(pages_config, url_context, local_file_urls=False): previous = None for path, title in pages_config: - url = utils.get_url_path(path, local_file_urls) + url = utils.get_url_path(path, use_directory_urls) title, sep, child_title = title.partition('/') title = title.strip() child_title = child_title.strip() diff --git a/mkdocs/utils.py b/mkdocs/utils.py index b6515e54..0e3d36cf 100644 --- a/mkdocs/utils.py +++ b/mkdocs/utils.py @@ -60,7 +60,7 @@ def get_html_path(path): return os.path.join(path, 'index.html') -def get_url_path(path, local_file_urls=False): +def get_url_path(path, use_directory_urls=True): """ Map a source file path to an output html path. @@ -68,12 +68,12 @@ def get_url_path(path, local_file_urls=False): Paths like 'about.md' will be converted to '/about/' Paths like 'api-guide/core.md' will be converted to '/api-guide/core/' - If `local_file_urls` is `True`, returned URLs will include the a trailing + If `use_directory_urls` is `False`, returned URLs will include the a trailing `index.html` rather than just returning the directory path. """ path = get_html_path(path) url = '/' + path.replace(os.path.pathsep, '/') - if not local_file_urls: + if use_directory_urls: return url[:-len('index.html')] return url