From 6531ca9dee67bc439e9f2d23c0dc697829c4838b Mon Sep 17 00:00:00 2001 From: Heli Aldridge Date: Tue, 19 Nov 2024 10:42:53 -0500 Subject: [PATCH] DOP-5205: Improve onboarding docs --- HACKING.md | 30 +++++++++++++++++++++++++++++- README.rst | 9 +++++++++ docs/flowchart.svg | 1 + 3 files changed, 39 insertions(+), 1 deletion(-) create mode 100644 docs/flowchart.svg diff --git a/HACKING.md b/HACKING.md index 70c6b35c..aba5a976 100644 --- a/HACKING.md +++ b/HACKING.md @@ -1,5 +1,7 @@ # Snooty Parser +![Data flowchart](./docs/flowchart.svg) + ## Organization The snooty parser has the following key parts: @@ -145,7 +147,7 @@ To release snooty, do the following: 1. Make sure you are on the `main` branch. -2. Ensure that the "Unreleased" section of CHANGELOG.md is up-to-date and +2. Ensure that the "Unreleased" section of CHANGELOG.md is up-to-date and commit any changes you've made. 3. Run `make cut-release BUMP_TO_VERSION=`. @@ -184,3 +186,29 @@ tag if it was created. * Flutter is currently a fork to add support for line numbers. We need to figure out a cleaner way of doing this so we can merge it into the upstream codebase. + +## Glossary + +
+
reStructuredText
+
A markup language identified with the Python ecosystem.
+ +
Abstract Syntax Tree (AST)
+
A tree of nodes which reflect the syntactic structure of an unparsed textual document.
+ +
Postprocessor
+
The component of snooty which performs global link analysis and other forms of processing that spans multiple files.
+ +
docutils
+
The canonical parsing library for reStructuredText.
+ + +
tinydocutils
+
Our vendored fork of docutils, modified to be statically typed and less reliant on method dispatch through string manipulation.
+ +
Giza
+
The primary entry point of the docs' original tech stack: it would download assets, generate reStructuredText from YAML files (hence the `gizaparser/` directory for compatibility), and invoke Sphinx.
+ +
Sphinx
+
The primary unofficially official documentation toolchain for reStructuredText.
+
diff --git a/README.rst b/README.rst index ddff0122..5ec26427 100644 --- a/README.rst +++ b/README.rst @@ -1,2 +1,11 @@ The Snooty Parser ================= + +The Snooty Parser is a tool that takes a reStructuredText documentation corpus and +generates a node tree suitable for straightforward conversion into HTML. + +Development +----------- + +Snooty developers should refer to ``__ for documentation on internals and +how to work on the Snooty Parser. diff --git a/docs/flowchart.svg b/docs/flowchart.svg new file mode 100644 index 00000000..220f2c27 --- /dev/null +++ b/docs/flowchart.svg @@ -0,0 +1 @@ + \ No newline at end of file