def main(cmd, args, options=None): """ Build the documentation, and optionally start the devserver. """ clean_site_dir = 'clean' in options if cmd == 'serve': config = load_config(options=options) serve(config, options=options) elif cmd == 'build': config = load_config(options=options) build(config, clean_site_dir=clean_site_dir) elif cmd == 'json': config = load_config(options=options) build(config, dump_json=True, clean_site_dir=clean_site_dir) elif cmd == 'gh-deploy': config = load_config(options=options) build(config, clean_site_dir=clean_site_dir) gh_deploy(config) elif cmd == 'new': new(args, options) else: config = load_config(options=options) event = events.CLI(config, cmd, args, options) event.broadcast() if not event.consumed: std = ['help', 'new', 'build', 'serve', 'gh-deply', 'json'] cmds = '|'.join(std + list(events.CLI.commands)) print('mkdocs [%s] {options}' % cmds)
def test_config_option(self): """ Users can explicitly set the config file using the '--config' option. Allows users to specify a config other than the default `mkdocs.yml`. """ expected_result = { 'site_name': 'Example', 'pages': [{ 'Introduction': 'index.md' }], } file_contents = dedent(""" site_name: Example pages: - 'Introduction': 'index.md' """) with TemporaryDirectory() as temp_path: os.mkdir(os.path.join(temp_path, 'docs')) config_path = os.path.join(temp_path, 'mkdocs.yml') config_file = open(config_path, 'w') config_file.write(file_contents) config_file.flush() config_file.close() result = config.load_config(config_file=config_file.name) self.assertEqual(result['site_name'], expected_result['site_name']) self.assertEqual(result['pages'], expected_result['pages'])
def setUpClass(cls) -> None: """ various setup code such as; - cloning test repository from GitHub into a temporary directory - setting up a basic argparse to test the cli commands """ # cloning the test repository try: os.chdir(TestEntry.temp_dir_path) print('attempting to download test repository', TestEntry.git_repo, 'to directory', TestEntry.temp_dir_path) subprocess.run(['git', 'clone', TestEntry.git_repo], check=True) os.chdir(os.listdir()[0]) except OSError as e: print(e) print( 'failed to change directory. Could be because the temporary directory was not created' ) except Exception as e: print(e) print('git clone failed') else: TestEntry.setUpFailed = False # failing the test should the setup fail if TestEntry.setUpFailed: TestEntry.fail(TestEntry, 'setup failed. Stopping tests') # loading mkdocs.yml and failing tests if loading fails try: TestEntry.cfg = config.load_config('mkdocs.yml') except Exception as e: print(e) TestEntry.fail(TestEntry, 'setup failed. Stopping tests')
def test_config_option(self): """ Users can explicitly set the config file using the '--config' option. Allows users to specify a config other than the default `mkdocs.yml`. """ expected_result = { 'site_name': 'Example', 'pages': [ {'Introduction': 'index.md'} ], } file_contents = dedent(""" site_name: Example pages: - ['index.md', 'Introduction'] """) config_file = tempfile.NamedTemporaryFile('w', delete=False) try: config_file.write(ensure_utf(file_contents)) config_file.flush() config_file.close() result = config.load_config(config_file=config_file.name) self.assertEqual(result['site_name'], expected_result['site_name']) self.assertEqual(result['pages'], expected_result['pages']) finally: os.remove(config_file.name)
def run_build(theme_name, output, config_file, quiet): """ Given a theme name and output directory use the configuration for the MkDocs documentation and overwrite the site_dir and theme. If no output is provided, serve the documentation on each theme, one at a time. """ options = { 'theme': theme_name, } if config_file is None: config_file = open(MKDOCS_CONFIG, 'rb') if not quiet: print("Using config: {0}".format(config_file.name)) if not os.path.exists(output): os.makedirs(output) options['site_dir'] = os.path.join(output, theme_name) if not quiet: print("Building {0}".format(theme_name)) try: conf = config.load_config(config_file=config_file, **options) config_file.close() build.build(conf) build.build(conf, dump_json=True) except Exception: print("Error building: {0}".format(theme_name), file=sys.stderr) raise
def test_deploy_no_cname(self, mock_isfile, mock_import, get_remote, get_sha, is_repo): config = load_config( remote_branch='test', ) gh_deploy.gh_deploy(config)
def builder(lang): log.info(f'Building {lang}...') pre_build(lang, docs_dir) lang_path = os.path.join(docs_dir, lang) config = load_config(config_file=os.path.join(lang_path, 'mkdocs.yml'), dev_addr=f'{host}:{port}', strict=True, site_dir=os.path.join(site_dir, lang)) config['site_url'] = f'http://{host}:{port}/{lang}/' # mkdocs is usually launched from the docs root directory, so it doesn't resolve relative paths smart enough, # leading to some bugs when launched from another place. # For example, custom_icons don't work without this dirty hack, and our neat Flipper buttons fail to load :( # I could've filled an issue to mkdocs-material-extensions regarding this, but I believe it's more reliable # to just switch the working directory, cause there might be other features that rely on it. # # It was kinda hard to figure this out, and it's actually 9 AM right now and I haven't slept yet, so please # satisfy my praise kink by saying 'good girl' telepathically cwd = os.getcwd() os.chdir(lang_path) build(config, live_server=True, dirty=False) os.chdir(cwd)
def get_plugin_config_from_mkdocs( self, mkdocs_yml_filepath: Path, plugin_name: str ) -> Config: """Load a mkdocs.yml and returns the configuration for the specified plugin. :param mkdocs_yml_filepath: path to MkDocs configuration file :type mkdocs_yml_filepath: Path :param plugin_name: plugin name (as mentionned into the mkdocs.yml) :type plugin_name: str :return: plugin configuration loaded by MkDocs. Empty if specified plugin is \ not enabled into the mkdocs.yml. :rtype: Config """ # instanciate plugin cfg_mkdocs = load_config(str(mkdocs_yml_filepath.resolve())) plugins = cfg_mkdocs.get("plugins") if "rss" not in plugins: logging.warning( f"Plugin {plugin_name} is not part of enabled plugin in the MkDocs " "configuration file: {mkdocs_yml_filepath}" ) return {} plugin_loaded = plugins.get("rss") cfg = plugin_loaded.on_config(cfg_mkdocs) logging.info("Fixture configuration loaded: " + str(cfg)) return plugin_loaded.config
def builder(): log.info("Building documentation...") config = load_config( config_file=config_file, dev_addr=dev_addr, strict=strict, theme=theme, theme_dir=theme_dir, site_dir=site_dir, **kwargs ) # combine CLI watch arguments with config file values if config["watch"] is None: config["watch"] = watch else: config["watch"].extend(watch) # Override a few config settings after validation config['site_url'] = 'http://{}{}'.format(config['dev_addr'], mount_path(config)) live_server = livereload in ['dirty', 'livereload'] dirty = livereload == 'dirty' build(config, live_server=live_server, dirty=dirty) return config
def gh_deploy_command(config_file, clean): """Deply your documentation to GitHub Pages""" config = load_config( config_file=config_file ) build.build(config, clean_site_dir=clean) gh_deploy.gh_deploy(config)
def HandleYaml(confFile): ''' 从YAML文件,处理课程目录 ''' conf = config.load_config(config_file=confFile) pages = conf["pages"] for category in pages: for categoryName, values in category.items(): for item in values: for level1_key, level1_value in item.items(): title1 = level1_key if isinstance(level1_value, unicode): title = " - ".join([categoryName, level1_key]) HandleSingle(title, level1_value) elif isinstance(level1_value, list): for item in level1_value: for level2_key, level2_value in item.items(): if isinstance(level2_value, list): for item in level2_value: for level3_key, level3_value in item.items( ): title = " - ".join([ categoryName, level1_key, level2_key, level3_key ]) HandleSingle(title, level3_value) else: title = " - ".join( [categoryName, level1_key, level2_key]) HandleSingle(title, level2_value) else: # None pp.pprint("Fatal Error")
def test_config_option(self): """ Users can explicitly set the config file using the '--config' option. Allows users to specify a config other than the default `mkdocs.yml`. """ expected_result = { 'site_name': 'Example', 'pages': [['index.md', 'Introduction']], } file_contents = dedent(""" site_name: Example pages: - ['index.md', 'Introduction'] """) config_file = tempfile.NamedTemporaryFile('w', delete=False) try: config_file.write(ensure_utf(file_contents)) config_file.flush() options = {'config': config_file.name} result = config.load_config(options=options) self.assertEqual(result['site_name'], expected_result['site_name']) self.assertEqual(result['pages'], expected_result['pages']) config_file.close() finally: os.remove(config_file.name)
def render_content(input_content, pre_article_id, next_article_id): input_content = input_content.replace('\r\n', ' \r\n') config = load_config( config_file=settings.BASE_DIR + '/blog_django/utils/mkdocs.yml', docs_dir=settings.BASE_DIR + '/blog_django/utils/docs', ) site_navigation = nav.SiteNavigation(config['pages'], config['use_directory_urls']) for page in site_navigation.walk_pages(): pass # Process the markdown text html_content, table_of_contents, meta = convert_markdown( markdown_source=input_content, config=config, site_navigation=site_navigation) html_content = html_content.replace('src="./', 'src="/') # 添加视频 html_content = re.sub("(?P<video><p>@video_start@.*?@video_end@</p>)", sub_video, html_content) context = get_global_context(site_navigation, config) context['base_url'] = '/static/mk_docs' context.update( get_page_context(page, html_content, table_of_contents, meta, config)) context['page'].next_article_id = next_article_id context['page'].pre_article_id = pre_article_id return context
def sync(args): """ Pulls the previously built pages from github pages Args: args (argparse.Namespace): A Namespace object contaning all the command line arguments Raises: exceptions.ConfigurationError """ cfg = config.load_config(config_file=args.config_file) with tempfile.TemporaryDirectory() as tempdir: # clone gh-pages branch into a temp dir os.chdir(tempdir) subprocess.run( ['git', 'clone', '-b', cfg['remote_branch'], cfg['repo_url']]) # noinspection PyArgumentList os.chdir(os.listdir()[0]) # remove old site folder try: shutil.rmtree(cfg['site_dir']) os.mkdir(cfg['site_dir'] ) # rmtree deletes folder so you need to recreate folder except FileNotFoundError as identifier: print(identifier) print('no site directory') # copy files into site directory with os.scandir(os.getcwd()) as files: for i in files: print(i.name, i.path) shutil.move(i.path, cfg['site_dir'])
def mkdocs_site(tmpdir): mkdocs_root = os.path.join(os.path.dirname(os.path.realpath(__file__)), 'test_data') cfg = config.load_config(os.path.join(mkdocs_root, 'mkdocs.yml')) cfg['site_dir'] = tmpdir build.build(cfg)
def test_config_option(self): """ Users can explicitly set the config file using the '--config' option. Allows users to specify a config other than the default `mkdocs.yml`. """ expected_result = { 'site_name': 'Example', 'pages': [ {'Introduction': 'index.md'} ], } file_contents = dedent(""" site_name: Example pages: - 'Introduction': 'index.md' """) with TemporaryDirectory() as temp_path: os.mkdir(os.path.join(temp_path, 'docs')) config_path = os.path.join(temp_path, 'mkdocs.yml') config_file = open(config_path, 'w') config_file.write(ensure_utf(file_contents)) config_file.flush() config_file.close() result = config.load_config(config_file=config_file.name) self.assertEqual(result['site_name'], expected_result['site_name']) self.assertEqual(result['pages'], expected_result['pages'])
def on_any_event(self, event): if not isinstance(event, events.DirModifiedEvent): time.sleep(0.05) print 'Rebuilding documentation...', config = load_config(options=self.options) build(config, live_server=True) print ' done'
def test_invalid_config(self): file_contents = dedent(""" - ['index.md', 'Introduction'] - ['index.md', 'Introduction'] - ['index.md', 'Introduction'] """) config_file = tempfile.NamedTemporaryFile('w', delete=False) try: config_file.write(file_contents) config_file.flush() config_file.close() with self.assertRaises(ConfigurationError): config.load_config(config_file=open(config_file.name, 'rb')) finally: os.remove(config_file.name)
def publish(context, skip_update_ipns): Printer.start("Publishing your site to IPFS...") with cd(DEFAULT_SITE_DIR): Printer.info("Building site...") build(load_config(config_file='./mkdocs.yml')) if not os.path.exists(IPFS_BIN): Printer.error("Please run 'hfs2018 init' first") context.abort() Printer.info( 'Uploading to IPFS and updating IPNS record (optional). This may take some time...' ) with ipfs_daemon(IPFS_BIN): site_output_dir = os.path.join(DEFAULT_SITE_DIR, "site") Printer.info("We are uploading the site to IPFS now...") site_hash = add_to_ipfs(site_output_dir) Printer.info( f"The site is available at https://gateway.ipfs.io/ipfs/{site_hash}" ) if not skip_update_ipns: Printer.info("We are updating the IPNS record now...") ipns_hash = update_ipns_record(site_hash) Printer.ready( f'Your site is available on IPNS! You can reach it via:' f' https://gateway.ipfs.io/ipns/{ipns_hash}')
def json_command(clean, config_file, strict, site_dir): """Build the MkDocs documentation to JSON files Rather than building your documentation to HTML pages, this outputs each page in a simple JSON format. This command is useful if you want to index your documentation in an external search engine. """ log.warning("The json command is deprecated and will be removed in a " "future MkDocs release. For details on updating: " "http://www.mkdocs.org/about/release-notes/") # Don't override config value if user did not specify --strict flag # Conveniently, load_config drops None values strict = strict or None try: build.build(config.load_config( config_file=config_file, strict=strict, site_dir=site_dir ), dump_json=True, dirty=not clean) except exceptions.ConfigurationError as e: # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def build_command(clean, config_file, strict, theme): """Build the MkDocs documentation""" build.build(load_config( config_file=config_file, strict=strict, theme=theme ), clean_site_dir=clean)
def json_command(clean, config_file, strict, site_dir): """Build the MkDocs documentation to JSON files Rather than building your documentation to HTML pages, this outputs each page in a simple JSON format. This command is useful if you want to index your documentation in an external search engine. """ log.warning("The json command is deprecated and will be removed in a " "future MkDocs release. For details on updating: " "http://www.mkdocs.org/about/release-notes/") # Don't override config value if user did not specify --strict flag # Conveniently, load_config drops None values strict = strict or None try: build.build(config.load_config( config_file=config_file, strict=strict, site_dir=site_dir ), dump_json=True, dirty=not clean) except exceptions.ConfigurationError as e: # pragma: no cover # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def gh_deploy_command(config_file, clean, message, remote_branch): """Deply your documentation to GitHub Pages""" config = load_config( config_file=config_file, remote_branch=remote_branch ) build.build(config, clean_site_dir=clean) gh_deploy.gh_deploy(config, message=message)
def serve_command(dev_addr, config_file, strict, theme): """Run the builtin development server""" serve.serve(load_config( config_file=config_file, dev_addr=dev_addr, strict=strict, theme=theme, ))
def buildTo(branch): print 'Building doc pages for: %s...' % (branch) branchCfg = config.load_config() if branchCfg['extra']['version'] != branch: updateConfigVersion(branch) sh.mkdocs('build', '--site-dir', 'site/%s' % (branch)) if branchCfg['extra']['version'] != branch: sh.git('checkout', '--', 'mkdocs.yml')
def handle_mkdocs_ghdeploy(): delete_branch('gh-pages') cfg = config.load_config( config_file=os.path.join(CWD, "docs/mkdocs.yml"), repo_url='[email protected]:sumeetpatil/TravisTest.git') build.build(cfg) print('Deploying {} Github Pages to {}#gh-pages') gh_deploy.gh_deploy(cfg, force=True)
def build_command(clean, **kwargs): """Build the MkDocs documentation""" try: build.build(config.load_config(**kwargs), dirty=not clean) except exceptions.ConfigurationError as e: # pragma: no cover # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def handle_mkdocs_ghdeploy(to_ghdeploy, kind, remote): if to_ghdeploy: delete_branch('gh-pages') cfg = config.load_config(config_file=os.path.join( CWD, select_config(kind)), remote_name=remote) build.build(cfg) print('Deploying {} Github Pages to {}#gh-pages'.format(kind, remote)) gh_deploy.gh_deploy(cfg, force=True)
def main(cmd, args, options=None): """ Build the documentation, and optionally start the devserver. """ if cmd == 'serve': config = load_config(options=options) serve(config, options=options) elif cmd == 'build': config = load_config(options=options) build(config) elif cmd == 'gh-deploy': config = load_config(options=options) build(config) gh_deploy(config) elif cmd == 'new': new(args, options) else: print('mkdocs [help|new|build|serve|gh-deploy] {options}')
def gh_deploy_command(clean, message, remote_branch, remote_name, force, ignore_version, shell, **kwargs): """Deploy your documentation to GitHub Pages""" cfg = config.load_config( remote_branch=remote_branch, remote_name=remote_name, **kwargs ) build.build(cfg, dirty=not clean) gh_deploy.gh_deploy(cfg, message=message, force=force, ignore_version=ignore_version, shell=shell)
def test_deploy_error(self, mock_log, mock_import): error_string = 'TestError123' mock_import.return_value = (False, error_string) config = load_config(remote_branch='test', ) self.assertRaises(SystemExit, gh_deploy.gh_deploy, config) mock_log.error.assert_called_once_with( 'Failed to deploy to GitHub with error: \n%s', error_string)
def buildForTest(): print "Building site pages..." updateConfigVersion('develop') sh.rm('-rf', 'site') sh.mkdocs('build', '--clean') sh.git('checkout', '--', 'mkdocs.yml') cfg = config.load_config() for version in cfg['extra']['versions']: deployVersion(version)
def build(cwd, site_dir): cfg = config.load_config() # sanity check - the version dirs exist as named for version in cfg['extra']['versions']: if not 'separate' in version or not version['separate']: d = os.path.join('versions', version['dir']) print('Verifying dir %s' % (d)) if not os.path.isdir(d): print("The directory %s does not exist" % (d)) return # sanity check - dependent_repos exist in '..' for repo in dependent_repos: d = os.path.join(cwd, '..', repo) print('Verifying repo dependency in %s' % (d)) if not os.path.isdir(d): print("The directory %s does not exist" % (d)) return # sanity check - only one latest latest = False for version in cfg['extra']['versions']: if not latest and 'latest' in version and version['latest']: print('Latest is %s' % (version['dir'])) latest = True elif latest and 'latest' in version and version['latest']: print('ERROR: More than one version is latest.') print('Only one version can be latest: True.') print('Check mkdocs.yml.') return print("Building site pages") sh.rm('-rf', site_dir) sh.mkdocs('build', '--clean', '--site-dir', site_dir) for version in cfg['extra']['versions']: print("Building doc pages for: %s" % (version['dir'])) if not 'separate' in version or not version['separate']: sh.mkdocs('build', '--site-dir', os.path.join(site_dir, version['dir']), _cwd=os.path.join("versions", version['dir'])) else: repo_dir = os.path.join(cwd, '..', 'mynewt-documentation') if version['dir'] != 'master': repo_dir = os.path.join(repo_dir, 'versions', version['dir'], 'mynewt-documentation') sh.make('clean', _cwd=repo_dir) sh.make('docs', _cwd=repo_dir) sh.mv(os.path.join(repo_dir, '_build', 'html'), os.path.join(site_dir, version['dir'])) if 'latest' in version and version['latest']: sh.ln('-s', version['dir'], 'latest', _cwd=site_dir)
def test_deploy_error(self, mock_log, mock_import): error_string = 'TestError123' mock_import.return_value = (False, error_string) config = load_config( remote_branch='test', ) self.assertRaises(SystemExit, gh_deploy.gh_deploy, config) mock_log.error.assert_called_once_with('Failed to deploy to GitHub with error: \n%s', error_string)
def builder(): log.info("Building documentation...") config = load_config( config_file=config_file, dev_addr=dev_addr, strict=strict, theme=theme, ) config['site_dir'] = tempdir build(config, live_server=True) return config
def gh_deploy_command(config_file, clean, message, remote_branch, remote_name): """Deploy your documentation to GitHub Pages""" try: config = load_config(config_file=config_file, remote_branch=remote_branch, remote_name=remote_name) build.build(config, clean_site_dir=clean) gh_deploy.gh_deploy(config, message=message) except exceptions.ConfigurationError as e: # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def build_command(clean, config_file, strict, theme, site_dir): """Build the MkDocs documentation""" try: build.build(load_config( config_file=config_file, strict=strict, theme=theme, site_dir=site_dir ), clean_site_dir=clean) except exceptions.ConfigurationError as e: # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def main(cmd, args, options=None): """ Build the documentation, and optionally start the devserver. """ if cmd == 'serve': config = load_config(options=options) serve(config, options=options) elif cmd == 'build': config = load_config(options=options) build(config) elif cmd == 'json': config = load_config(options=options) build(config, dump_json=True) elif cmd == 'gh-deploy': config = load_config(options=options) build(config) gh_deploy(config) elif cmd == 'new': new(args, options) else: print('mkdocs [help|new|build|serve|gh-deploy|json] {options}')
def serve(config, options=None): """ Start the devserver, and rebuild the docs whenever any changes take effect. """ # Create a temporary build directory, and set some options to serve it tempdir = tempfile.mkdtemp() options['site_dir'] = tempdir # Only use user-friendly URLs when running the live server options['use_directory_urls'] = True # Perform the initial build config = load_config(options=options) build(config, live_server=True) # Note: We pass any command-line options through so that we # can re-apply them if the config file is reloaded. event_handler = BuildEventHandler(options) config_event_handler = ConfigEventHandler(options) # We could have used `Observer()`, which can be faster, but # `PollingObserver()` works more universally. observer = PollingObserver() observer.schedule(event_handler, config['docs_dir'], recursive=True) for theme_dir in config['theme_dir']: if not os.path.exists(theme_dir): continue observer.schedule(event_handler, theme_dir, recursive=True) observer.schedule(config_event_handler, '.') observer.start() class TCPServer(socketserver.TCPServer): allow_reuse_address = True class DocsDirectoryHandler(FixedDirectoryHandler): base_dir = config['site_dir'] host, port = config['dev_addr'].split(':', 1) server = TCPServer((host, int(port)), DocsDirectoryHandler) print('Running at: http://%s:%s/' % (host, port)) print('Live reload enabled.') print('Hold ctrl+c to quit.') try: server.serve_forever() except KeyboardInterrupt: print('Stopping server...') # Clean up observer.stop() observer.join() shutil.rmtree(tempdir) print('Quit complete')
def gh_deploy_command(config_file, clean, message, remote_branch): """Deply your documentation to GitHub Pages""" try: config = load_config( config_file=config_file, remote_branch=remote_branch ) build.build(config, clean_site_dir=clean) gh_deploy.gh_deploy(config, message=message) except exceptions.ConfigurationError as e: # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def json_command(clean, config_file, strict): """Build the MkDocs documentation to JSON files Rather than building your documentation to HTML pages, this outputs each page in a simple JSON format. This command is useful if you want to index your documentation in an external search engine. """ build.build(load_config( config_file=config_file, strict=strict ), dump_json=True, clean_site_dir=clean)
def gh_deploy_command(config_file, clean, message, remote_branch, remote_name, force): """Deploy your documentation to GitHub Pages""" try: cfg = config.load_config( config_file=config_file, remote_branch=remote_branch, remote_name=remote_name ) build.build(cfg, dirty=not clean) gh_deploy.gh_deploy(cfg, message=message, force=force) except exceptions.ConfigurationError as e: # pragma: no cover # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def main(cmd, args, options=None): """ Build the documentation, and optionally start the devserver. """ clean_site_dir = 'clean' in options if cmd == 'serve': config = load_config(options=options) serve(config, options=options) elif cmd == 'build': config = load_config(options=options) build(config, clean_site_dir=clean_site_dir) elif cmd == 'json': config = load_config(options=options) build(config, dump_json=True, clean_site_dir=clean_site_dir) elif cmd == 'gh-deploy': config = load_config(options=options) build(config, clean_site_dir=clean_site_dir) gh_deploy(config) elif cmd == 'new': new(args, options) else: print('MkDocs (version {0})'.format(__version__)) print('mkdocs [help|new|build|serve|gh-deploy|json] {options}')
def builder(): log.info("Building documentation...") config = load_config( config_file=config_file, dev_addr=dev_addr, strict=strict, theme=theme, theme_dir=theme_dir ) config['site_dir'] = tempdir live_server = livereload in ['dirty', 'livereload'] dirty = livereload == 'dirty' build(config, live_server=live_server, dirty=dirty) return config
def _load_config(config_file, strict, site_dir): cfg = config.load_config( config_file=config_file, strict=strict, site_dir=site_dir, theme='mkdocs' ) # TODO: We should not need to manually update settings like this. version_assets = os.path.join(os.path.dirname(__file__), 'assets') # Add the assets for the version switcher cfg['theme_dir'].append(version_assets) cfg['extra_javascript'].append('mkdocs_versioned/js/version_picker.js') return cfg
def docs_deploy(DOCS_ROOT=None, **ctx): """ """ import mkdocs from mkdocs.config import load_config from mkdocs.gh_deploy import gh_deploy mkdocs_config = os.path.join(DOCS_ROOT, 'mkdocs.yml') assert os.path.exists(mkdocs_config) os.chdir(DOCS_ROOT) try: config = load_config( config_file=mkdocs_config, ) gh_deploy(config) except mkdocs.exceptions.ConfigurationError as e: # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def builder(): log.info("Building documentation...") config = load_config( config_file=config_file, dev_addr=dev_addr, strict=strict, theme=theme, theme_dir=theme_dir, site_dir=site_dir ) # Override a few config settings after validation config['site_url'] = 'http://{0}/'.format(config['dev_addr']) live_server = livereload in ['dirty', 'livereload'] dirty = livereload == 'dirty' build(config, live_server=live_server, dirty=dirty) return config
def json_command(clean, config_file, strict): """Build the MkDocs documentation to JSON files Rather than building your documentation to HTML pages, this outputs each page in a simple JSON format. This command is useful if you want to index your documentation in an external search engine. """ log.warning("The json command is deprcated and will be removed in a future " "MkDocs release. For details on updating: " "http://www.mkdocs.org/about/release-notes/") build.build(load_config( config_file=config_file, strict=strict ), dump_json=True, clean_site_dir=clean)
def run_build(theme_name, output=None, config_file=None, quiet=False): """ Given a theme name and output directory use the configuration for the MkDocs documentation and overwrite the site_dir and theme. If no output is provided, serve the documentation on each theme, one at a time. """ should_serve = output is None options = {} if not serve: if not os.path.exists(output): os.makedirs(output) options['site_dir'] = os.path.join(output, theme_name) if config_file is None: config_file = open(MKDOCS_CONFIG, 'rb') if not quiet: print("Using config: {0}".format(config_file)) cli.configure_logging() conf = config.load_config(config_file=config_file, theme=theme_name) if should_serve: if not quiet: print("Serving {0}".format(theme_name)) try: serve.serve(conf) except KeyboardInterrupt: return else: if not quiet: print("Building {0}".format(theme_name)) try: with capture_stdout() as out: build.build(conf) build.build(conf, dump_json=True) except Exception: print("Failed building {0}".format(theme_name), file=sys.stderr) raise if not quiet: print(''.join(out))
def build_command(clean, config_file, strict, theme, theme_dir, site_dir): """Build the MkDocs documentation""" # Don't override config value if user did not specify --strict flag # Conveniently, load_config drops None values strict = strict or None try: build.build(config.load_config( config_file=config_file, strict=strict, theme=theme, theme_dir=theme_dir, site_dir=site_dir ), dirty=not clean) except exceptions.ConfigurationError as e: # Avoid ugly, unhelpful traceback raise SystemExit('\n' + str(e))
def serve(config, options=None): """ Start the devserver, and rebuild the docs whenever any changes take effect. """ # Create a temporary build directory, and set some options to serve it tempdir = tempfile.mkdtemp() options['site_dir'] = tempdir # Only use user-friendly URLs when running the live server options['use_directory_urls'] = True # Perform the initial build config = load_config(options=options) build(config, live_server=True) # Note: We pass any command-line options through so that we # can re-apply them if the config file is reloaded. event_handler = BuildEventHandler(options) config_event_handler = ConfigEventHandler(options) observer = observers.Observer() observer.schedule(event_handler, config['docs_dir'], recursive=True) observer.schedule(event_handler, config['theme_dir'], recursive=True) observer.schedule(config_event_handler, '.') observer.start() class TCPServer(socketserver.TCPServer): allow_reuse_address = True class DocsDirectoryHandler(FixedDirectoryHandler): base_dir = config['site_dir'] host, port = config['dev_addr'].split(':', 1) server = TCPServer((host, int(port)), DocsDirectoryHandler) print('Running at: http://%s:%s/' % (host, port)) print('Live reload enabled.') print('Hold ctrl+c to quit.') server.serve_forever() # Clean up observer.stop() observer.join() shutil.rmtree(tempdir)