From c6d6101f2ae5e133a7995611aef5738656956bd5 Mon Sep 17 00:00:00 2001 From: Ocre42 Date: Wed, 11 Dec 2019 15:16:44 +0000 Subject: [PATCH] Linting and document --- README.rst | 67 ++---------------------------------------------------- gen.py | 4 +--- 2 files changed, 3 insertions(+), 68 deletions(-) diff --git a/README.rst b/README.rst index df7591ab..75194f91 100644 --- a/README.rst +++ b/README.rst @@ -50,69 +50,6 @@ Set up a virtual environment: Build the documentation::: - ./gen.sh + ./gen_rst.sh -The built documentation is now in ``docs//_build/dirhtml`` - - -Editing the documentation -========================= - -Make any changes in ``IATI-Extra-Documentation``, as the ``docs`` directory is generated from -this and other sources each time ``./gen.sh`` is run. - - -Building a website that also includes additonal guidance -======================================================== - -There is additonal guidance in the following git repositories: - -* https://github.com/IATI/IATI-Guidance -* https://github.com/IATI/IATI-Developer-Documentation/ - -These are not versioned with the standard, so are not included in this repository (`IATI-Standard-SSOT `__) or its submodules. - -To generate a copy of the website with these extra repositories included, run: - -.. code-block:: bash - - # If you have not done already create the docs directory as a git repository - # (more info below) - mkdir docs - cd docs - git init - cd .. - # Actually run the generate script - ./combined_gen.sh - -This generates the website in the ``docs`` directory, but then copies it to ``docs-copy`` at the end, so that a webserver can be pointed to ``docs-copy/en/_build/dirhtml`` and not be interrupted when the site is being rebuilt. - -The ``docs`` directory should be a git repository in order to support adding the "Last updated" line to the bottom of the page. We build the live and dev websites in different directories so that the last updated date corresponds to when the site was actually changed, not when the relevant commit was added to the source git respository. - - -Generating a local version with the IATI theme -============================================== - -A local version of the website (with the full IATI theme) can be generated after cloning the theme files and setting up the required symlinks for Sphinx to follow when generating the HTML files. - -.. code-block:: bash - - # Clone the repository containing the IATI theme at the same level where you cloned IATI-Standard-SSOT - git clone https://github.com/IATI/IATI-Websites.git IATI-Websites - - # Set-up symlinks to the template file/folders - # for the symlinks to work, you'll have to be inside the IATI-Extra-Documentation folder cloned inside IATI-Standard-SSOT - cd IATI-Extra-Documentation/en - ln -s ../../../IATI-Websites/iatistandard/_templates/ ./ - ln -s ../../../IATI-Websites/iatistandard/_static/ ./ - ln -s ../../../IATI-Websites/iatistandard/_templates/layout_dev.html ./_templates/layout.html - - # Generate a version of the documentation - cd ../../ - ./combined_gen.sh - - # The documentation HTML files are stored in the `docs-copy/en/_build/dirhtml` folder - # You can navigate around your generated version of the site using a Python HTTP webserver - cd docs-copy/en/_build/dirhtml - python3 -m http.server - # View the site in a browser at http://0.0.0.0:8000/ +The built documentation is now in ``outputs//_build/dirhtml`` as json files diff --git a/gen.py b/gen.py index d6651b39..36390577 100644 --- a/gen.py +++ b/gen.py @@ -323,7 +323,6 @@ def output_docs(self, element_name, path, element=None, minOccurs='', maxOccurs= } json.dump(outputdict, fp, indent=2) - def output_schema_table(self, element_name, path, element=None, output=False, filename='', title='', minOccurs='', maxOccurs='', ref_element=None, type_element=None): if element is None: element = self.get_schema_element('element', element_name) @@ -362,7 +361,7 @@ def output_schema_table(self, element_name, path, element=None, output=False, fi if output: for row in rows: - row['match_codelists'] = match_codelists('/'.join(path.split('/')[1:])+row['path']) + row['match_codelists'] = match_codelists('/'.join(path.split('/')[1:]) + row['path']) row['ruleset_text'] = ruleset_text(row['path']) with open(os.path.join('outputs', self.lang, filename), 'w') as fp: @@ -563,7 +562,6 @@ def codelists_to_docs(lang): 'path_to_ref': path_to_ref(path) }) - with open(os.path.join('outputs', rst_filename), 'w') as fp: outputdict = { 'codelist_json': codelist_json,