From 89d88fa5f3eca4c162bc9bf5aad920899b976099 Mon Sep 17 00:00:00 2001 From: "Jason M. Gates" Date: Wed, 28 Feb 2024 16:41:59 -0700 Subject: [PATCH] docs: Update links Update various links after moving `shell-logger` out onto GitHub. --- doc/source/abstract_method.rst | 1 - doc/source/html_utilities.rst | 37 ++++++++++++++++++++++-- doc/source/index.rst | 52 ++++++++++++++++------------------ doc/source/shell.rst | 3 +- doc/source/shell_logger.rst | 3 -- doc/source/stats_collector.rst | 5 ---- doc/source/trace.rst | 4 --- 7 files changed, 60 insertions(+), 45 deletions(-) diff --git a/doc/source/abstract_method.rst b/doc/source/abstract_method.rst index dbb420d..0b3aca7 100644 --- a/doc/source/abstract_method.rst +++ b/doc/source/abstract_method.rst @@ -2,4 +2,3 @@ AbstractMethod ============== .. autoexception:: shell_logger.abstract_method.AbstractMethod - :noindex: diff --git a/doc/source/html_utilities.rst b/doc/source/html_utilities.rst index 781b4ba..0b6e23c 100644 --- a/doc/source/html_utilities.rst +++ b/doc/source/html_utilities.rst @@ -4,5 +4,38 @@ HTML Utilities The following are a number of utility functions used to generate the HTML log file produced by :class:`ShellLogger`. -.. automodule:: shell_logger.html_utilities - :noindex: +.. autofunction:: shell_logger.html_utilities.append_html +.. autofunction:: shell_logger.html_utilities.child_logger_card +.. autofunction:: shell_logger.html_utilities.child_logger_card_html +.. autofunction:: shell_logger.html_utilities.closing_html_text +.. autofunction:: shell_logger.html_utilities.command_card +.. autofunction:: shell_logger.html_utilities.command_card_html +.. autofunction:: shell_logger.html_utilities.command_detail +.. autofunction:: shell_logger.html_utilities.command_detail_list +.. autofunction:: shell_logger.html_utilities.diagnostics_card +.. autofunction:: shell_logger.html_utilities.disk_time_series_plot +.. autofunction:: shell_logger.html_utilities.embed_html +.. autofunction:: shell_logger.html_utilities.embed_script +.. autofunction:: shell_logger.html_utilities.embed_style +.. autofunction:: shell_logger.html_utilities.fixed_width +.. autofunction:: shell_logger.html_utilities.flatten +.. autofunction:: shell_logger.html_utilities.get_human_time +.. autofunction:: shell_logger.html_utilities.html_encode +.. autofunction:: shell_logger.html_utilities.html_header +.. autofunction:: shell_logger.html_utilities.html_message_card +.. autofunction:: shell_logger.html_utilities.load_template +.. autofunction:: shell_logger.html_utilities.message_card +.. autofunction:: shell_logger.html_utilities.nested_simplenamespace_to_dict +.. autofunction:: shell_logger.html_utilities.opening_html_text +.. autofunction:: shell_logger.html_utilities.output_block +.. autofunction:: shell_logger.html_utilities.output_block_card +.. autofunction:: shell_logger.html_utilities.output_block_html +.. autofunction:: shell_logger.html_utilities.output_line_html +.. autofunction:: shell_logger.html_utilities.parent_logger_card_html +.. autofunction:: shell_logger.html_utilities.sgr_24bit_color_to_html +.. autofunction:: shell_logger.html_utilities.sgr_4bit_color_and_style_to_html +.. autofunction:: shell_logger.html_utilities.sgr_8bit_color_to_html +.. autofunction:: shell_logger.html_utilities.sgr_to_html +.. autofunction:: shell_logger.html_utilities.split_template +.. autofunction:: shell_logger.html_utilities.stat_chart_card +.. autofunction:: shell_logger.html_utilities.time_series_plot diff --git a/doc/source/index.rst b/doc/source/index.rst index e80b5b2..45562db 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -19,16 +19,18 @@ while logging various metadata, statistics, and trace information. Any time you're tempted to write your own wrapper around things like :class:`subprocess.Popen` or :func:`subprocess.run`, consider using :func:`ShellLogger.log` instead. If you're familiar with `the Unix script -command `_, this is -similar in principle, but with substantially more functionality. If you're -familiar with `Python's logging module -`_, the motivation is similar, -but this intends to capture what's happening *in the shell* rather than in -Python itself. +command`_, this is similar in principle, but with substantially more +functionality. If you're familiar with `Python's logging module`_, the +motivation is similar, but this intends to capture what's happening *in the +shell* rather than in Python itself. -The following talk from the `US-RSE Virtual Workshop 2021 -`_ illustrates the module's -functionality. +.. _the Unix script command: https://man7.org/linux/man-pages/man1/script.1.html +.. _Python's logging module: https://docs.python.org/3/library/logging.html + +The following talk from the `US-RSE Virtual Workshop 2021`_ illustrates the +module's functionality. + +.. _US-RSE Virtual Workshop 2021: https://us-rse.org/virtual-workshop-2021/ .. raw:: html @@ -53,11 +55,12 @@ functionality. Where to Get shell-logger ------------------------- -The source repository for this module can be found `here -`_. See the project's -`README.md -`_ -for details on how to clone, install, and otherwise interact with the project. +The source repository for this module can be found `on GitHub`_. See the +project's `README`_ for details on how to clone, install, and otherwise +interact with the project. + +.. _on GitHub: https://github.com/sandialabs/shell-logger +.. _README: https://github.com/sandialabs/shell-logger/blob/master/README.md Using shell-logger ------------------ @@ -105,6 +108,7 @@ the following: .. literalinclude:: ../../example/hello_world_html.py :language: python :linenos: + :lines: 11- :caption: ``example/hello_world_html.py`` Running the script yields @@ -112,10 +116,8 @@ Running the script yields .. code-block:: This example demonstrates logging information solely to the HTML log file. - Open /Users/jmgate/workspace/shell-logger/example/log_hello_world_html/2021-09-22_14.56.42.558599_szt68acx/Hello_ShellLogger.html to view the log. + Open /log_hello_world_html/_/Hello_ShellLogger.html to view the log. -You can view the generated HTML log file `here -`__. When you open that file, you'll see something like .. image:: images/html_log.png @@ -175,12 +177,10 @@ highlighted lines below. .. literalinclude:: ../../example/hello_world_html_and_console.py :language: python :linenos: - :emphasize-lines: 11, 13 + :lines: 11- + :emphasize-lines: 15-16, 22-23 :caption: ``example/hello_world_html_and_console.py`` -You can view the generated HTML log file `here -`__. - Example 3: Collecting Statistics ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -191,12 +191,10 @@ and **Example 1** are the highlighted lines below. .. literalinclude:: ../../example/hello_world_html_with_stats.py :language: python :linenos: - :emphasize-lines: 12, 14 + :lines: 11- + :emphasize-lines: 16, 22 :caption: ``example/hello_world_html_with_stats.py`` -You can view the generated HTML log file `here -`__. - Example 4: Building a Code ^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -215,11 +213,9 @@ The equivalent Python script using ``shell-logger`` is the following: .. literalinclude:: ../../example/build_flex.py :language: python :linenos: + :lines: 11- :caption: ``example/build_flex.py`` -You can view the generated HTML log file `here -`__. - More Details ------------ diff --git a/doc/source/shell.rst b/doc/source/shell.rst index d5c47f6..0ddc9ef 100644 --- a/doc/source/shell.rst +++ b/doc/source/shell.rst @@ -1,5 +1,4 @@ Shell ===== -.. automodule:: shell_logger.shell - :noindex: +.. autoclass:: shell_logger.shell.Shell diff --git a/doc/source/shell_logger.rst b/doc/source/shell_logger.rst index 9e3d888..adcfd1a 100644 --- a/doc/source/shell_logger.rst +++ b/doc/source/shell_logger.rst @@ -2,13 +2,11 @@ ShellLogger =========== .. autoclass:: shell_logger.ShellLogger - :noindex: JSON Serialization ------------------ .. autoclass:: shell_logger.ShellLoggerDecoder - :noindex: .. todo:: @@ -16,4 +14,3 @@ JSON Serialization base class as well. .. autoclass:: shell_logger.ShellLoggerEncoder - :noindex: diff --git a/doc/source/stats_collector.rst b/doc/source/stats_collector.rst index 74824d8..af57b64 100644 --- a/doc/source/stats_collector.rst +++ b/doc/source/stats_collector.rst @@ -2,25 +2,20 @@ StatsCollector ============== .. autoclass:: shell_logger.stats_collector.StatsCollector - :noindex: .. automethod:: shell_logger.stats_collector::stats_collectors - :noindex: DiskStatsCollector ------------------ .. autoclass:: shell_logger.stats_collector.DiskStatsCollector - :noindex: CPUStatsCollector ----------------- .. autoclass:: shell_logger.stats_collector.CPUStatsCollector - :noindex: MemoryStatsCollector -------------------- .. autoclass:: shell_logger.stats_collector.MemoryStatsCollector - :noindex: diff --git a/doc/source/trace.rst b/doc/source/trace.rst index fd8284f..f48daff 100644 --- a/doc/source/trace.rst +++ b/doc/source/trace.rst @@ -2,19 +2,15 @@ Trace ===== .. autoclass:: shell_logger.trace.Trace - :noindex: .. automethod:: shell_logger.trace::trace_collector - :noindex: STrace ------ .. autoclass:: shell_logger.trace.STrace - :noindex: LTrace ------ .. autoclass:: shell_logger.trace.LTrace - :noindex: