From e849bc4df6af79fccc046e87c4aeff30e6d4f980 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 09:45:56 -0700 Subject: [PATCH 01/11] Create .readthedocs.yaml Add default configuration file which is now required. --- .readthedocs.yaml | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..963875202 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,18 @@ +# Read the Docs configuration file for Sphinx projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + formats: + - pdf + - epub From 8de3f0bb2325ba8a408e162fa5443a186f3a8de9 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 09:48:31 -0700 Subject: [PATCH 02/11] Fix the `.readthedocs.yml` config `formats:` value. --- .readthedocs.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 963875202..b8853fab0 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,6 +13,7 @@ build: # Build documentation in the "docs/" directory with Sphinx sphinx: configuration: docs/conf.py - formats: - - pdf - - epub + +formats: + - pdf + - epub From ed44e7a9016ed142f793d2c957416370e6ce146e Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 09:57:12 -0700 Subject: [PATCH 03/11] Try `.readthedocs.yaml` without config file. --- .readthedocs.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index b8853fab0..362da6a2a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,7 +12,6 @@ build: # Build documentation in the "docs/" directory with Sphinx sphinx: - configuration: docs/conf.py formats: - pdf From 77e8609a1010d2c948a71d8ab9b3a1a1000d3cb9 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 10:02:19 -0700 Subject: [PATCH 04/11] No config file in `.readthedocs.yml` attempt two. --- .readthedocs.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 362da6a2a..f173d15d2 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -12,7 +12,8 @@ build: # Build documentation in the "docs/" directory with Sphinx sphinx: - + configuration: + formats: - pdf - epub From 394c9ef2ee2dff1bb74a38c55c5523ae90a89bdc Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 10:06:28 -0700 Subject: [PATCH 05/11] Adding minimal `conf.py` file Adding a minimal `conf.py` file to the `docs` directory based on the last passing build @ https://readthedocs.org/projects/verible/builds/21293135/ Still unclear if rtd will still add the remaining bits needed. --- doc/conf.py | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) create mode 100644 doc/conf.py diff --git a/doc/conf.py b/doc/conf.py new file mode 100644 index 000000000..b57fd3aae --- /dev/null +++ b/doc/conf.py @@ -0,0 +1,28 @@ +# -*- coding: utf-8 -*- + +from __future__ import division, print_function, unicode_literals + +from datetime import datetime + +from recommonmark.parser import CommonMarkParser + +extensions = [] +templates_path = ['templates', '_templates', '.templates'] +source_suffix = ['.rst', '.md'] +source_parsers = { + '.md': CommonMarkParser, + } +master_doc = 'index' +project = u'verible' +copyright = str(datetime.now().year) +version = 'latest' +release = 'latest' +exclude_patterns = ['_build'] +pygments_style = 'sphinx' +htmlhelp_basename = 'verible' +html_theme = 'sphinx_rtd_theme' +file_insertion_enabled = False +latex_documents = [ + ('index', 'verible.tex', u'verible Documentation', + u'', 'manual'), +] From 1d091d4fb87dced372ff21498e7ebb1a5cd03302 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 10:11:41 -0700 Subject: [PATCH 06/11] Adding `requirements.txt` for docs Following https://blog.readthedocs.com/defaulting-latest-build-tools/ somewhat. --- doc/requirements.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 doc/requirements.txt diff --git a/doc/requirements.txt b/doc/requirements.txt new file mode 100644 index 000000000..845228634 --- /dev/null +++ b/doc/requirements.txt @@ -0,0 +1,6 @@ +sphinx +sphinx-rtd-theme +pillow +mock +commonmark +recommonmark From 7d3ffc65b70362d8d1b20cc3c21c8f61eb592ab6 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 10:14:29 -0700 Subject: [PATCH 07/11] Install dependencies from `doc/requirements.txt` RTD used to have sensible defaults :-/ --- .readthedocs.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index f173d15d2..0d6cad340 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -14,6 +14,10 @@ build: sphinx: configuration: +python: + install: + - requirements: doc/requirements.txt + formats: - pdf - epub From d54573f88d505c6cbbbdbf713120f6a98b28674b Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 10:30:19 -0700 Subject: [PATCH 08/11] Creating basic `index.rst` file Seems like this is needed now. Still unsure how to use the top level `README.md` file for now. --- doc/index.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) create mode 100644 doc/index.rst diff --git a/doc/index.rst b/doc/index.rst new file mode 100644 index 000000000..54bf89d3d --- /dev/null +++ b/doc/index.rst @@ -0,0 +1,18 @@ +Using Verible +============= + +.. toctree:: + :maxdepth: 2 + + style_lint + formatter + indexing + +Developing Verible +================== + +.. toctree:: + :maxdepth: 2 + + development + parser_design From bc630c04c2dd93a20446c853b989fb7baf4a8f91 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 10:48:55 -0700 Subject: [PATCH 09/11] Adding file extensions? Trying to get the docs working. --- doc/index.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/index.rst b/doc/index.rst index 54bf89d3d..679d3be4e 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,9 +4,9 @@ Using Verible .. toctree:: :maxdepth: 2 - style_lint - formatter - indexing + style_lint.md + formatter.md + indexing.md Developing Verible ================== @@ -14,5 +14,5 @@ Developing Verible .. toctree:: :maxdepth: 2 - development - parser_design + development.md + parser_design.md From 485b839b7ad01aa141db70c7a3c323142c3adbba Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 11:02:22 -0700 Subject: [PATCH 10/11] Switch docs to use `myst_parser` for Markdown parsing Seeing if this change fixes the documentation output. --- doc/conf.py | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index b57fd3aae..82644c3bc 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -1,17 +1,14 @@ # -*- coding: utf-8 -*- -from __future__ import division, print_function, unicode_literals - from datetime import datetime -from recommonmark.parser import CommonMarkParser - -extensions = [] +extensions = ['myst_parser'] templates_path = ['templates', '_templates', '.templates'] source_suffix = ['.rst', '.md'] source_parsers = { - '.md': CommonMarkParser, - } + '.rst': 'restructuredtext', + '.md': 'markdown', +} master_doc = 'index' project = u'verible' copyright = str(datetime.now().year) @@ -23,6 +20,5 @@ html_theme = 'sphinx_rtd_theme' file_insertion_enabled = False latex_documents = [ - ('index', 'verible.tex', u'verible Documentation', - u'', 'manual'), + ('index', 'verible.tex', u'verible Documentation', u'', 'manual'), ] From b46ddb485fb09c017465aff83045921d895ca325 Mon Sep 17 00:00:00 2001 From: Tim 'mithro' Ansell Date: Sat, 29 Jun 2024 11:06:16 -0700 Subject: [PATCH 11/11] Update `requirements.txt` for `myst-parser` usage. --- doc/requirements.txt | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/doc/requirements.txt b/doc/requirements.txt index 845228634..2ebad7602 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -2,5 +2,4 @@ sphinx sphinx-rtd-theme pillow mock -commonmark -recommonmark +myst-parser