From a8346496a5413d02c3530a321fe157685be6064a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Hugo=20H=C3=B6rnquist?= <hugo@lysator.liu.se> Date: Mon, 18 Sep 2023 21:36:25 +0200 Subject: [PATCH] Documentation work. --- doc/.gitignore | 2 +- doc/doc-gather.rst | 30 ++++++++++++++++++++++++++++ doc/formatting-output.rst | 7 +++++++ doc/index.rst | 12 ++++++++---- doc/muppet.rst | 39 +++++++++++++++++++++++++++++++++++++ doc/output-formats.rst | 29 +++++++++++++++++++++++++++ doc/parser-combinator.rst | 2 ++ doc/syntax-highlighting.rst | 8 ++++++++ 8 files changed, 124 insertions(+), 5 deletions(-) create mode 100644 doc/doc-gather.rst create mode 100644 doc/formatting-output.rst create mode 100644 doc/muppet.rst create mode 100644 doc/output-formats.rst create mode 100644 doc/parser-combinator.rst create mode 100644 doc/syntax-highlighting.rst diff --git a/doc/.gitignore b/doc/.gitignore index eebb7a8..e85f14c 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -1,2 +1,2 @@ -muppet*.rst +muppet.*.rst modules.rst diff --git a/doc/doc-gather.rst b/doc/doc-gather.rst new file mode 100644 index 0000000..2e23c65 --- /dev/null +++ b/doc/doc-gather.rst @@ -0,0 +1,30 @@ +Gathering information +===================== + +For each module (``get_module``) + +run ``puppet-strings`` (todo hyperlink) on the module, using the hash +of ``metadata.json`` as the cache key + + +Manual documentation files +-------------------------- + +``*.md`` + ``LICENSE`` + + +Parsing Puppet Code +------------------- + +``puppet strings --format json`` is run, generating a json +representation of the Puppet code. However, this format is overly +verbose. So it's passed to ``muppet.puppet.parser.puppet_parser`` +(TODO link) which transforms it into a much simpler json tree. + +This is then passed to ``muppet.puppet.ast.build_ast`` (TODO link) +which creates an AST in python objects. + +These modes can be tested with + +.. code-block:: sh + python -m muppet.puppet {parser,ast,serialize} diff --git a/doc/formatting-output.rst b/doc/formatting-output.rst new file mode 100644 index 0000000..5edf7ff --- /dev/null +++ b/doc/formatting-output.rst @@ -0,0 +1,7 @@ +Formatting Output +================= + +.. toctree:: + + syntax-highlighting + diff --git a/doc/index.rst b/doc/index.rst index f26c9c6..fb3d599 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -6,13 +6,17 @@ Welcome to Muppet Strings's documentation! ========================================== +Muppet Strings is a tool for documenting entire Puppet environments. + .. toctree:: - :maxdepth: 2 + :maxdepth: 3 :caption: Contents: - modules - -Here is some content. + doc-gather + output-formats + syntax-highlighting + parser-combinator + muppet Indices and tables ================== diff --git a/doc/muppet.rst b/doc/muppet.rst new file mode 100644 index 0000000..326920e --- /dev/null +++ b/doc/muppet.rst @@ -0,0 +1,39 @@ +muppet package +============== + +Subpackages +----------- + +.. toctree:: + :maxdepth: 4 + + muppet.puppet + muppet.syntax_highlight + +Submodules +---------- + +.. toctree:: + :maxdepth: 4 + + muppet.breadcrumbs + muppet.cache + muppet.format + muppet.gather + muppet.intersperse + muppet.lookup + muppet.markdown + muppet.output + muppet.parser_combinator + muppet.symbols + muppet.tabs + muppet.templates + muppet.util + +Module contents +--------------- + +.. automodule:: muppet + :members: + :undoc-members: + :show-inheritance: diff --git a/doc/output-formats.rst b/doc/output-formats.rst new file mode 100644 index 0000000..6b83ab2 --- /dev/null +++ b/doc/output-formats.rst @@ -0,0 +1,29 @@ +Output Formats +============== + +TODO something here about how output can be generated (see +muppet.puppet.format) + + +Output is handled module per module. + +- index.html +- *REFERENCE*/index.html +- ... +- manifests/ + - *classname* + - index.html + - source.pp.html + - source.pp.txt + - ... + +For each *class* (or *resource*, *type-alias*, ...) a directory is +generated. The index.html contains the documentation for the class, +followed by the source code, but syntax highlighted and hyperlinked. + +TODO link to parser combinator usage here. + +TODO source.pp.html isn't needed since "rendered" now contains the +original source code. + +source.pp.txt contains the unaltered source, as it appeared on disk. diff --git a/doc/parser-combinator.rst b/doc/parser-combinator.rst new file mode 100644 index 0000000..a556aba --- /dev/null +++ b/doc/parser-combinator.rst @@ -0,0 +1,2 @@ +Parser Combinator +================= diff --git a/doc/syntax-highlighting.rst b/doc/syntax-highlighting.rst new file mode 100644 index 0000000..97db1a4 --- /dev/null +++ b/doc/syntax-highlighting.rst @@ -0,0 +1,8 @@ +Syntax Highlighting +=================== + +andre simons +plain +pygments + +__init__ finds best possible match -- GitLab