From eb914e9e08c84f749815302e1733c10117f45a8a Mon Sep 17 00:00:00 2001 From: Tom Aarsen Date: Fri, 15 Oct 2021 13:19:17 +0200 Subject: [PATCH 1/3] Modernize nltk.org/howto pages --- .gitignore | 1 + nltk/test/corpus.doctest | 2 +- web/_templates/doctest.rst | 5 +++++ web/conf.py | 34 ++++++++++++++++++++++++++++++++++ web/howto.rst | 8 ++++++++ web/index.rst | 2 +- 6 files changed, 50 insertions(+), 2 deletions(-) create mode 100644 web/_templates/doctest.rst create mode 100644 web/howto.rst diff --git a/.gitignore b/.gitignore index 91e14c9321..be11c74413 100644 --- a/.gitignore +++ b/.gitignore @@ -40,6 +40,7 @@ coverage.xml # automatically built files for website web/api/*.rst +web/howto/*.rst # iPython notebooks diff --git a/nltk/test/corpus.doctest b/nltk/test/corpus.doctest index 6544aa2331..536ef452fa 100644 --- a/nltk/test/corpus.doctest +++ b/nltk/test/corpus.doctest @@ -25,7 +25,7 @@ and new corpus reader classes. Section `Regression Tests`_ and associated functions and classes. .. contents:: **Table of Contents** - :depth: 2 + :depth: 4 :backlinks: none --------------------- diff --git a/web/_templates/doctest.rst b/web/_templates/doctest.rst new file mode 100644 index 0000000000..143710147b --- /dev/null +++ b/web/_templates/doctest.rst @@ -0,0 +1,5 @@ +{% for item in range(17 + module_name|length) -%}#{%- endfor %} +Sample usage for {{ module_name }} +{% for item in range(17 + module_name|length) -%}#{%- endfor %} + +.. include:: ../../nltk/test/{{ module_name }}.doctest diff --git a/web/conf.py b/web/conf.py index d4341f2e69..b143f107f5 100644 --- a/web/conf.py +++ b/web/conf.py @@ -54,6 +54,40 @@ def run_apidoc(app): ) +def generate_howto(): + """Custom function for generating contents in the ``howto`` folder, + based on the ``ntlk/test/*.doctest`` files. + """ + import glob + import re + + from jinja2 import Template + + modules = [] + + web_folder = os.path.dirname(os.path.abspath(__file__)) + + # Load jinja templates + with open(os.path.join(web_folder, "_templates", "doctest.rst")) as f: + doctest_template = Template(f.read()) + + print("Generating HOWTO pages...") + # Iterate over .doctest files, and find the module_name. + pattern = re.compile(r"(\w+)\.doctest$") + for path in glob.glob(os.path.join(web_folder, "..", "nltk", "test", "*.doctest")): + match = pattern.search(path) + module_name = match.group(1) + # Write .rst files based on the doctest_template. + doctest_template.stream(module_name=module_name).dump( + os.path.join(web_folder, "howto", f"{module_name}.rst") + ) + modules.append(module_name) + + print(f"Generated {len(modules)} HOWTO pages.") + + +generate_howto() + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/web/howto.rst b/web/howto.rst new file mode 100644 index 0000000000..ac9fc9505c --- /dev/null +++ b/web/howto.rst @@ -0,0 +1,8 @@ +Example usage of NLTK modules +============================= + +.. toctree:: + :titlesonly: + :glob: + + howto/* diff --git a/web/index.rst b/web/index.rst index 51557025c8..4481c553c8 100644 --- a/web/index.rst +++ b/web/index.rst @@ -76,7 +76,7 @@ Next Steps :caption: NLTK Documentation API Reference - Example Usage + Example Usage Module Index Wiki FAQ From 82fc54f8935bbb1aec6c6a76cf756d617c686f19 Mon Sep 17 00:00:00 2001 From: Tom Aarsen Date: Fri, 15 Oct 2021 14:05:54 +0200 Subject: [PATCH 2/3] Don't make a HTML page for index.doctest --- web/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/web/conf.py b/web/conf.py index b143f107f5..296dae73f9 100644 --- a/web/conf.py +++ b/web/conf.py @@ -67,7 +67,7 @@ def generate_howto(): web_folder = os.path.dirname(os.path.abspath(__file__)) - # Load jinja templates + # Load jinja template with open(os.path.join(web_folder, "_templates", "doctest.rst")) as f: doctest_template = Template(f.read()) @@ -77,6 +77,9 @@ def generate_howto(): for path in glob.glob(os.path.join(web_folder, "..", "nltk", "test", "*.doctest")): match = pattern.search(path) module_name = match.group(1) + # Ignore index.doctest, we already have an index, i.e. howto.rst + if module_name == "index": + continue # Write .rst files based on the doctest_template. doctest_template.stream(module_name=module_name).dump( os.path.join(web_folder, "howto", f"{module_name}.rst") From 4b40405109deecc43103810fb1bdd19f81406010 Mon Sep 17 00:00:00 2001 From: Tom Aarsen Date: Fri, 15 Oct 2021 16:30:13 +0200 Subject: [PATCH 3/3] Ensure howto folder exists --- web/conf.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/web/conf.py b/web/conf.py index 296dae73f9..6391b105a8 100644 --- a/web/conf.py +++ b/web/conf.py @@ -66,6 +66,9 @@ def generate_howto(): modules = [] web_folder = os.path.dirname(os.path.abspath(__file__)) + howto_folder = os.path.join(web_folder, "howto") + if not os.path.exists(howto_folder): + os.makedirs(howto_folder) # Load jinja template with open(os.path.join(web_folder, "_templates", "doctest.rst")) as f: @@ -82,7 +85,7 @@ def generate_howto(): continue # Write .rst files based on the doctest_template. doctest_template.stream(module_name=module_name).dump( - os.path.join(web_folder, "howto", f"{module_name}.rst") + os.path.join(howto_folder, f"{module_name}.rst") ) modules.append(module_name)