From: Vladimír Vondruš Date: Sun, 12 May 2019 14:42:33 +0000 (+0200) Subject: documentation/python: introduce the INPUT option for specifying input dir. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=aa5db04b0ea07bcafc04c96b2af0941eb6f58785;p=blog.git documentation/python: introduce the INPUT option for specifying input dir. --- diff --git a/doc/documentation/python.rst b/doc/documentation/python.rst index ceed523b..00061f93 100644 --- a/doc/documentation/python.rst +++ b/doc/documentation/python.rst @@ -143,6 +143,12 @@ Variable Description :py:`PROJECT_SUBTITLE` to the documentation main page, similarly as `shown here <{filename}/css/page-layout.rst#link-back-to-main-site-from-a-subsite>`_. +:py:`INPUT: str` Base input directory. If not set, config + file base dir is used. Relative paths are + relative to config file base dir. +:py:`OUTPUT: str` Where to save the output. Relative paths + are relative to :py:`INPUT`; if not set, + ``output/`` is used. :py:`INPUT_MODULES: List[Any]` List of modules to generate the docs from. Values can be either strings or module objects. See `Module inspection`_ for more @@ -150,9 +156,6 @@ Variable Description :py:`INPUT_PAGES: List[str]` List of :abbr:`reST ` files for standalone pages. See `Pages`_ for more information. -:py:`OUTPUT: str` Where to save the output. Relative paths - relative are to the config file base dir; - if not set, ``output/`` is used. :py:`THEME_COLOR: str` Color for :html:``, corresponding to the CSS style. If empty, no :html:`` tag is rendered. See @@ -160,15 +163,15 @@ Variable Description :py:`FAVICON: str` Favicon URL, used to populate :html:``. If empty, no :html:`` tag is rendered. Relative - paths are searched relative to the config - file base dir and to the ``python.py`` - script dir as a fallback. See - `Theme selection`_ for more information. + paths are searched relative to :py:`INPUT` + and to the ``python.py`` script dir as a + fallback. See `Theme selection`_ for more + information. :py:`STYLESHEETS: List[str]` List of CSS files to include. Relative - paths are searched relative to the config - file base dir and to the ``python.py`` - script dir as a fallback. See `Theme selection`_ - for more information. + paths are searched relative to :py:`INPUT` + and to the ``python.py`` script dir as a + fallback. See `Theme selection`_ for more + information. :py:`HTML_HEADER: str` HTML code to put at the end of the :html:`` element. Useful for linking arbitrary JavaScript code or, for example, @@ -179,9 +182,8 @@ Variable Description :py:`EXTRA_FILES: List[str]` List of extra files to copy (for example additional CSS files that are :css:`@import`\ ed from the primary one). Relative paths are - searched relative to the config file base - dir and to the ``python.py`` script dir as - a fallback. + searched relative to :py:`INPUT` and to the + ``python.py`` script dir as a fallback. :py:`LINKS_NAVBAR1: List[Any]` Left navbar column links. See `Navbar links`_ for more information. :py:`LINKS_NAVBAR2: List[Any]` Right navbar column links. See diff --git a/documentation/python.py b/documentation/python.py index ec14d007..eb88ab24 100755 --- a/documentation/python.py +++ b/documentation/python.py @@ -56,9 +56,10 @@ default_config = { 'PROJECT_TITLE': 'My Python Project', 'PROJECT_SUBTITLE': None, 'MAIN_PROJECT_URL': None, + 'INPUT': None, + 'OUTPUT': 'output', 'INPUT_MODULES': [], 'INPUT_PAGES': [], - 'OUTPUT': 'output', 'THEME_COLOR': '#22272e', 'FAVICON': 'favicon-dark.png', 'STYLESHEETS': [ @@ -924,8 +925,12 @@ def run(basedir, config, templates): # Set up the plugins m.htmlsanity.register_mcss(config, env) + # Populate the INPUT, if not specified, make it absolute + if config['INPUT'] is None: config['INPUT'] = basedir + else: config['INPUT'] = os.path.join(basedir, config['INPUT']) + # Make the output dir absolute - config['OUTPUT'] = os.path.join(basedir, config['OUTPUT']) + config['OUTPUT'] = os.path.join(config['INPUT'], config['OUTPUT']) if not os.path.exists(config['OUTPUT']): os.makedirs(config['OUTPUT']) # Guess MIME type of the favicon @@ -944,7 +949,7 @@ def run(basedir, config, templates): state.class_index += [render_module(state, [module_name], module, env)] for page in config['INPUT_PAGES']: - state.page_index += render_page(state, [os.path.splitext(os.path.basename(page))[0]], os.path.join(basedir, page), env) + state.page_index += render_page(state, [os.path.splitext(os.path.basename(page))[0]], os.path.join(config['INPUT'], page), env) # Recurse into the tree and mark every node that has nested modules with # has_nestaable_children. @@ -987,8 +992,8 @@ def run(basedir, config, templates): if urllib.parse.urlparse(i).netloc: continue # If file is found relative to the conf file, use that - if os.path.exists(os.path.join(basedir, i)): - i = os.path.join(basedir, i) + if os.path.exists(os.path.join(config['INPUT'], i)): + i = os.path.join(config['INPUT'], i) # Otherwise use path relative to script directory else: diff --git a/documentation/test_python/page_input_subdir/sub/index.rst b/documentation/test_python/page_input_subdir/sub/index.rst new file mode 120000 index 00000000..aa421e1e --- /dev/null +++ b/documentation/test_python/page_input_subdir/sub/index.rst @@ -0,0 +1 @@ +../../page/index.rst \ No newline at end of file diff --git a/documentation/test_python/test_page.py b/documentation/test_python/test_page.py index b61415c8..6298025a 100644 --- a/documentation/test_python/test_page.py +++ b/documentation/test_python/test_page.py @@ -35,3 +35,15 @@ class Page(BaseTestCase): self.assertEqual(*self.actual_expected_contents('index.html')) self.assertEqual(*self.actual_expected_contents('another.html')) self.assertEqual(*self.actual_expected_contents('pages.html')) + +class PageInputSubdir(BaseTestCase): + def __init__(self, *args, **kwargs): + super().__init__(__file__, 'input_subdir', *args, **kwargs) + + def test(self): + self.run_python({ + 'INPUT': 'sub', + 'INPUT_PAGES': ['index.rst'] + }) + # The same output as Page, just the file is taken from elsewhere + self.assertEqual(*self.actual_expected_contents('index.html', '../page/index.html'))