From f20a06377ffaa5b6a3819b81987ccc523daff5e0 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 23 Apr 2024 10:46:51 -0400 Subject: [PATCH 01/12] Edits --- README.md | 112 +++++++++++++++++++++------------ doc/source/examples.rst | 10 +-- doc/source/getting-started.rst | 51 ++------------- doc/source/index.rst | 22 +++++-- doc/source/user-guide.rst | 6 ++ 5 files changed, 102 insertions(+), 99 deletions(-) create mode 100644 doc/source/user-guide.rst diff --git a/README.md b/README.md index aab7e7e..a53de9a 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,117 @@ -# PyAnsys quarto cheat sheet format +# PyAnsys Quarto Cheat Sheet +PyAnsys Quarto Cheat Sheet is an extension for using [Quarto](https://quarto.org/), an open +source scientific and technical publishing system, to render cheat sheets from plain text +markdown. + +## Prerequisites + +Before you can use PyAnsys Quarto Cheat Sheet, you must have Quarto installed. For installation +information, see [Getting Started](https://quarto.org/docs/getting-started/installation.html) in +the Quarto documenation. ## Installation -To use this extension, you must have [Quarto](https://quarto.org/docs/getting-started/installation.html) installed. +You can install PyAnsys Quarto Cheat Sheet from the GitHub repository or an +archive file. -### Install the extension +### Install from the GitHub repository -**From the github repository:** +From the GitHub repository, you can install the latest version of PyAnsys Quart Cheat Sheet +from the main branch or install a version from a specific release branch. -From main branch: +To install the latest version from the main branch, run this command: ```bash quarto use ansys-internal/pyansys-quarto-cheatsheet@main ``` -From a specific release: +To install the version from a specific release branch, rather than using ``@main``, use +the release branch: ```bash quarto use ansys-internal/pyansys-quarto-cheatsheet@v0.1.0 ``` -**From the archive file:** +### Install from an archive file + +To install from an archive file, first download the `cheat_sheet.zip` or `cheat_sheet.tar.gz` +archive file from the repsitory's [Releases](https://github.com/ansys-internal/pyansys-quarto-cheatsheet/releases) +page. -Download the cheat_sheet.zip or cheat_sheet.tar.gz file from the -[releases page](https://github.com/ansys-internal/pyansys-quarto-cheatsheet/releases) and run the following command: +Then, run the command that installs PyAnsys Quarto Cheat Sheet in the Quarto environment from +the ZIP or TAR.GZ file. The command creates an ``_extensions`` directory in the current +directory with all the extension's files. + +For a ZIP file, run this command: ```bash quarto use cheat_sheet.zip ``` -or + +For a TAR.GZ file, run this command: + ```bash quarto use cheat_sheet.tar.gz ``` -This command installs the extension in the quarto environment and creates -a ``_extensions`` directory in the current directory containing the extension files. - ## Usage +To render a cheat sheet as a PDF file, you run this command: + ```bash quarto render examples/cheat_sheet.qmd --to cheat_sheet-pdf ``` + ## Format options -- **version**: Specifies the version of the cheat sheet. +The YAML configuration file for the cheat sheet specifies the +format options: + +- **version**: Version of the cheat sheet. ```yaml version: 0.1 ``` -- **title**: Sets the title of the cheat sheet. +- **title**: Title of the cheat sheet. ```yaml title: PyMAPDL cheat sheet ``` -- **footer**: Defines the footer text. +- **footer**: Footer text of the cheat sheet. ```yaml footer: PyMAPDL cheat sheet ``` -- **footerlinks**: Specifies a list of links to display in the footer. -Each link should have a ``url`` and ``text``. +- **footerlinks**: List of links to display in the footer. +Each link must have a ``urls`` and ``text`` option. ```yaml footerlinks: - urls: https://mapdl.docs.pyansys.com/version/stable/ - text: PyMAPDL Documentation + text: PyMAPDL documentation ``` -- **format**: Determines the format of the cheat sheet. For PDF generation, use `cheat_sheet-pdf`. +- **format**: Format for rendering the cheat sheet. For PDF generation, use `cheat_sheet-pdf`. ```yaml format: cheat_sheet-pdf ``` -- **execute**: Controls the code output in the code cell. Refer to the -[quarto documentation](https://quarto.org/docs/reference/cells/cells-knitr.html#code-output) -for available options. +- **execute**: Controls code and cell output. While descriptions for key options follow, see +[Code Cells: Knitr](https://quarto.org/docs/reference/cells/cells-knitr.html) +in the Quarto documentation for descriptions of all available options. - - *eval*: If set to `false`, the code will not be executed. + - *eval*: Whether to evaluate code cells. If `False`, only echos the code into the output. ```yaml execute: eval: false ``` - - *echo*: If set to `false`, the code will not be displayed in the output. + - *echo*: Whether to include cell source code in rendered output. ```yaml execute: echo: false ``` - - *output*: If set to `false`, the output of the code will not be displayed. + - *output*: Whether to include the results of executing the code in the output. ```yaml execute: output: false ``` -### Example of a cheat sheet configuration file + +## Example of a cheat sheet configuration file ```yaml version: 0.1 @@ -102,12 +127,12 @@ execute: output: false ``` - > [!NOTE] > By default, code cells are executed. To disable execution, use the `execute` option. > > To disable execution and display of individual or multiple code cells, -> utilize the `eval`, `echo`and similar options within the code cell. +> use the `eval`, `echo`, and similar options within the code cell: + > ``` > #| eval: false > @@ -118,33 +143,38 @@ execute: > The output of the code cell is displayed by default. To disable the output, use the `execute` option. > > To disable the output of individual or multiple code cells, -> utilize the `output` option within the code cell. +> use the `output` option within the code cell: + > ``` > #| output: false > ``` -### ``_quarto.yml`` file +## The `_quarto.yml` file + The `_quarto.yml` file is a configuration file that contains all the metadata at the project level. -Refer to the [quarto documentation project](https://quarto.org/docs/projects/quarto-projects.html#project-metadata) -for more information. +For more information, see the [quarto documentation project](https://quarto.org/docs/projects/quarto-projects.html#project-metadata). + +If you want to change the output directory, add the following line to the `_quarto.yml` file: -if you want to change the output directory, add the following line to the `_quarto.yml` file. ```yaml output_dir: _build ``` -example of [``_quarto.yml``](_quarto.yml) file is placed in the current directory. +An example of a [_quarto.yml](_quarto.yml) file is placed in the current directory. ## Example -Example of a [cheat_sheet.qmd](cheat_sheet.qmd) file is placed in the current directory. -Example of complete cheat sheet for pymapdl is placed in [pymapdl cheat sheet](examples/pymapdl_cheat_sheet_example.qmd) file. -To render the pymapdl example cheat sheet, run the following command: +An example of a [cheat_sheet.qmd](cheat_sheet.qmd) file is placed in the current directory. +An example of a complete cheat sheet for PyMAPDL is placed in the [pymapdl_cheat_sheet_example_qmd](examples/pymapdl_cheat_sheet_example.qmd) file. + +To render the PyMAPDL example cheat sheet, run this command: + ```bash quarto render examples/pymapdl_cheat_sheet_example.qmd ``` + > [!TIP] > If you want to open a `.qmd` file in Jupyter Notebook, follow these steps: -> 1. Install `jupytext` by running the command: `pip install jupytext` -> 2. Install `jupyter` by running the command: `pip install jupyter` -> 3. Open the `.qmd` file in Jupyter Notebook with the command: `jupyter notebook cheat_sheet.qmd` +> 1. Install `jupytext` by running this command: `pip install jupytext` +> 2. Install `jupyter` by running this command: `pip install jupyter` +> 3. Open the `.qmd` file in Jupyter Notebook by running this command: `jupyter notebook cheat_sheet.qmd` diff --git a/doc/source/examples.rst b/doc/source/examples.rst index c9e0c6c..d65294a 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -1,13 +1,13 @@ Examples ======== -The following example is a simple ``.qmd`` file that uses the ``pyansys-quarto-cheat-sheet`` -package to create a cheat sheet for the PyAnsys module. +The following example is a simple ``.qmd`` file that uses PyAnsys Quarto Cheat Sheet +to render a cheat sheet for a PyAnsys module. .. literalinclude:: ../../examples/cheat_sheet.qmd :language: md -To render the cheat sheet, run the following command: +To render the cheat sheet, run this command: .. code-block:: bash @@ -19,11 +19,11 @@ Output The rendered cheat sheet is saved as ``cheat_sheet.pdf`` in the same directory as the input file. -The rendered cheat sheet can be downloaded by clicking the link below: +You can download the rendered cheat sheet by clicking the following link: .. button-link:: _static/cheat_sheet.pdf :ref-type: ref :color: info :align: center - Rendered pdf :octicon:`download;1em` + Rendered PDF :octicon:`download;1em` diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index 3098f1c..424c0df 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -1,50 +1,7 @@ -Getting started and basic usage -=============================== +Getting started +=============== .. include:: ../../README.md :parser: myst_parser.sphinx_ - :start-after: # PyAnsys quarto cheat sheet format - :end-before: > [!NOTE] - - -.. note:: - - By default, code cells are executed. To disable execution, use the `execute` option. - To turn off execution and display of individual or multiple code cells, utilize the `execute` option within the code cell. - - .. code-block:: python - :linenos: - - #| execute: false - #| eval: false - -.. important:: - - The output of the code cell is displayed by default. To turn off the output, use the `execute` option. - - To disable the output of individual or multiple code cells, - utilize the `output` option within the code cell. - - .. code-block:: python - :linenos: - - #| output: false - -``_quarto.yml`` file --------------------- - -The `_quarto.yml` file is a configuration file that contains all the metadata at the project level. -Refer to the `quarto documentation project `_ -for more information. - -if you want to change the output directory, add the following line to the `_quarto.yml` file. - -.. code-block:: yaml - - output_dir: _build - -if you want to clean the latex output, add the following line to the `_quarto.yml` file. - -.. code-block:: yaml - - latex-clean: true + :start-after: ## Prerequisites + :end-before: > ## Usage diff --git a/doc/source/index.rst b/doc/source/index.rst index f7ab0e9..e83ee14 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,8 +1,9 @@ -PyAnsys quarto cheat sheet -========================== +PyAnsys Quarto Cheat Sheet documentation |version| +================================================== -This is a quick reference guide for the `pyansys-quarto-cheat-sheet` package. -It is a collection of useful commands and tips for using the `pyansys-quarto-cheat-sheet` package. +PyAnsys Quarto Cheat Sheet is an extension for using [Quarto](https://quarto.org/), an open +source scientific and technical publishing system, to generate cheat sheets from plain text +markdown. .. grid:: 1 2 2 2 :gutter: 3 3 4 4 @@ -12,17 +13,26 @@ It is a collection of useful commands and tips for using the `pyansys-quarto-che :link: getting-started :link-type: doc - How to install and import the package and basic usage. + Learn how to install PyAnsys Quarto Cheat Sheet. + + .. grid-item-card:: User guide :fa:`book-open-reader` + :link: user-guide + :link-type: doc + + Understand how to use PyAnsys Quarto Cheat Sheet to generate + cheat sheets. .. grid-item-card:: Examples :fa:`code` :link: examples :link-type: doc - Examples of how to use the package. + Explore examples that show how to use PyAnsys Quarto Cheat Sheet to + generate cheat sheets. .. toctree:: :hidden: getting-started + user-guide examples diff --git a/doc/source/user-guide.rst b/doc/source/user-guide.rst new file mode 100644 index 0000000..0eb511e --- /dev/null +++ b/doc/source/user-guide.rst @@ -0,0 +1,6 @@ +User guide +========== + +.. include:: ../../README.md + :parser: myst_parser.sphinx_ + :start-after: # Usage From 19b45b3f59fbf29313623e9133480ab5cc787413 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 23 Apr 2024 14:48:46 -0400 Subject: [PATCH 02/12] Move doc content from README.MD to reStructuredText files and create a README.RST file --- README.md | 180 ----------------------- README.rst | 68 +++++++++ doc/.vale.ini | 2 - doc/source/examples.rst | 16 +- doc/source/getting-started.rst | 68 ++++++++- doc/source/index.rst | 18 ++- doc/source/user-guide.rst | 131 ++++++++++++++++- examples/cheat_sheet.qmd | 53 +++---- examples/pymapdl_cheat_sheet_example.qmd | 8 +- 9 files changed, 310 insertions(+), 234 deletions(-) delete mode 100644 README.md create mode 100644 README.rst diff --git a/README.md b/README.md deleted file mode 100644 index a53de9a..0000000 --- a/README.md +++ /dev/null @@ -1,180 +0,0 @@ -# PyAnsys Quarto Cheat Sheet - -PyAnsys Quarto Cheat Sheet is an extension for using [Quarto](https://quarto.org/), an open -source scientific and technical publishing system, to render cheat sheets from plain text -markdown. - -## Prerequisites - -Before you can use PyAnsys Quarto Cheat Sheet, you must have Quarto installed. For installation -information, see [Getting Started](https://quarto.org/docs/getting-started/installation.html) in -the Quarto documenation. - -## Installation - -You can install PyAnsys Quarto Cheat Sheet from the GitHub repository or an -archive file. - -### Install from the GitHub repository - -From the GitHub repository, you can install the latest version of PyAnsys Quart Cheat Sheet -from the main branch or install a version from a specific release branch. - -To install the latest version from the main branch, run this command: - -```bash -quarto use ansys-internal/pyansys-quarto-cheatsheet@main -``` - -To install the version from a specific release branch, rather than using ``@main``, use -the release branch: - -```bash -quarto use ansys-internal/pyansys-quarto-cheatsheet@v0.1.0 -``` - -### Install from an archive file - -To install from an archive file, first download the `cheat_sheet.zip` or `cheat_sheet.tar.gz` -archive file from the repsitory's [Releases](https://github.com/ansys-internal/pyansys-quarto-cheatsheet/releases) -page. - -Then, run the command that installs PyAnsys Quarto Cheat Sheet in the Quarto environment from -the ZIP or TAR.GZ file. The command creates an ``_extensions`` directory in the current -directory with all the extension's files. - -For a ZIP file, run this command: - -```bash -quarto use cheat_sheet.zip -``` - -For a TAR.GZ file, run this command: - -```bash -quarto use cheat_sheet.tar.gz -``` - -## Usage - -To render a cheat sheet as a PDF file, you run this command: - -```bash -quarto render examples/cheat_sheet.qmd --to cheat_sheet-pdf -``` - -## Format options - -The YAML configuration file for the cheat sheet specifies the -format options: - -- **version**: Version of the cheat sheet. -```yaml -version: 0.1 -``` -- **title**: Title of the cheat sheet. -```yaml -title: PyMAPDL cheat sheet -``` -- **footer**: Footer text of the cheat sheet. -```yaml -footer: PyMAPDL cheat sheet -``` -- **footerlinks**: List of links to display in the footer. -Each link must have a ``urls`` and ``text`` option. -```yaml -footerlinks: -- urls: https://mapdl.docs.pyansys.com/version/stable/ - text: PyMAPDL documentation -``` -- **format**: Format for rendering the cheat sheet. For PDF generation, use `cheat_sheet-pdf`. -```yaml -format: cheat_sheet-pdf -``` -- **execute**: Controls code and cell output. While descriptions for key options follow, see -[Code Cells: Knitr](https://quarto.org/docs/reference/cells/cells-knitr.html) -in the Quarto documentation for descriptions of all available options. - - - *eval*: Whether to evaluate code cells. If `False`, only echos the code into the output. - ```yaml - execute: - eval: false - ``` - - *echo*: Whether to include cell source code in rendered output. - ```yaml - execute: - echo: false - ``` - - *output*: Whether to include the results of executing the code in the output. - ```yaml - execute: - output: false - ``` - -## Example of a cheat sheet configuration file - -```yaml -version: 0.1 -title: PyMAPDL cheat sheet -footer: PyMAPDL cheat sheet -footerlinks: -- urls: https://mapdl.docs.pyansys.com/version/stable/ - text: PyMAPDL Documentation -format: cheat_sheet-pdf -execute: - eval: false - echo: false - output: false -``` - -> [!NOTE] -> By default, code cells are executed. To disable execution, use the `execute` option. -> -> To disable execution and display of individual or multiple code cells, -> use the `eval`, `echo`, and similar options within the code cell: - -> ``` -> #| eval: false -> -> #| echo: false -> ``` - -> [!IMPORTANT] -> The output of the code cell is displayed by default. To disable the output, use the `execute` option. -> -> To disable the output of individual or multiple code cells, -> use the `output` option within the code cell: - -> ``` -> #| output: false -> ``` - -## The `_quarto.yml` file - -The `_quarto.yml` file is a configuration file that contains all the metadata at the project level. -For more information, see the [quarto documentation project](https://quarto.org/docs/projects/quarto-projects.html#project-metadata). - -If you want to change the output directory, add the following line to the `_quarto.yml` file: - -```yaml -output_dir: _build -``` - -An example of a [_quarto.yml](_quarto.yml) file is placed in the current directory. - -## Example - -An example of a [cheat_sheet.qmd](cheat_sheet.qmd) file is placed in the current directory. -An example of a complete cheat sheet for PyMAPDL is placed in the [pymapdl_cheat_sheet_example_qmd](examples/pymapdl_cheat_sheet_example.qmd) file. - -To render the PyMAPDL example cheat sheet, run this command: - -```bash -quarto render examples/pymapdl_cheat_sheet_example.qmd -``` - -> [!TIP] -> If you want to open a `.qmd` file in Jupyter Notebook, follow these steps: -> 1. Install `jupytext` by running this command: `pip install jupytext` -> 2. Install `jupyter` by running this command: `pip install jupyter` -> 3. Open the `.qmd` file in Jupyter Notebook by running this command: `jupyter notebook cheat_sheet.qmd` diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..712ad37 --- /dev/null +++ b/README.rst @@ -0,0 +1,68 @@ +PyAnsys Quarto Cheat Sheet +========================== +|pyansys| |python| |pypi| |GH-CI| |MIT| + +.. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC + :target: https://docs.pyansys.com/ + :alt: PyAnsys + +.. |python| image:: https://img.shields.io/pypi/pyversions/urlinclude?logo=pypi + :target: https://pypi.org/project/urlinclude/ + :alt: Python + +.. |pypi| image:: https://img.shields.io/pypi/v/urlinclude.svg?logo=python&logoColor=white + :target: https://pypi.org/project/urlinclude + :alt: PyPI + +.. |GH-CI| image:: https://github.com/ansys-internal/pyansys-quarto-cheatsheet/actions/workflows/ci_cd.yml/badge.svg + :target: https://github.com/ansys-internal/pyansys-quarto-cheatsheet/actions/workflows/ci_cd.yml + :alt: GH-CI + +.. |MIT| image:: https://img.shields.io/badge/License-MIT-yellow.svg + :target: https://opensource.org/blog/license/mit + :alt: MIT + + +Overview +======== + +PyAnsys Quarto Cheat Sheet is an extension for using `Quarto `_, an open +source scientific and technical publishing system, to render cheat sheets from plain text +markdown and code. + +Documentation and issues +------------------------ + +Documentation for the latest stable release of PyAnsys Quarto Cheat Sheet is hosted +at `PyAnsys Quarto Cheat Sheet documentation `_. + +The documentation has these sections: + +- `Getting started `_: Learn + how to install PyAnsys Quarto Cheat Sheet. +- `User guide `_: Understand how + to use the YAML configuration file for a cheat sheet to format it. +- `Examples `_: Explore examples + that show how to use PyAnsys Quarto Cheat Sheet to create your own cheat sheets. + +In the upper right corner of the documentation's title bar, there is an option +for switching from viewing the documentation for the latest stable release +to viewing the documentation for the development version or previously +released versions. + +On the `PyAnsys Quarto Cheat Sheet Issues `_ +page, you can create issues to report bugs and request new features. On the +`Discussions `_ page on the Ansys Developer portal, +you can post questions, share ideas, and get community feedback. + +If you have general questions about the PyAnsys ecosystem, email +`pyansys.core@ansys.com `_. If your +question is specific to PyAnsys Quarto Cheat Sheet, ask your +question in an issue as described in the previous paragraph. + +License +------- + +PyAnsys Quarto Cheat Sheet is licensed under the `MIT License `_. + +PyAnsys Quarto Cheat Sheet makes no commercial claim over Ansys whatsoever. diff --git a/doc/.vale.ini b/doc/.vale.ini index f24b365..3165893 100644 --- a/doc/.vale.ini +++ b/doc/.vale.ini @@ -27,5 +27,3 @@ Vale.Terms = NO # Apply the following styles BasedOnStyles = Vale, Google - -Google.Headings = NO diff --git a/doc/source/examples.rst b/doc/source/examples.rst index d65294a..b7982a3 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -1,13 +1,16 @@ +.. _cheat_sheet_example: + Examples ======== -The following example is a simple ``.qmd`` file that uses PyAnsys Quarto Cheat Sheet -to render a cheat sheet for a PyAnsys module. +The `cheat_sheet.qmd `_ +file in the ``Examples`` directory is a simple QMD file that you can use as a template for creating +your own cheat sheets. .. literalinclude:: ../../examples/cheat_sheet.qmd :language: md -To render the cheat sheet, run this command: +To use PyAnsys Quarto Cheat Sheet to render this QMD file as a cheat sheet in PDF format, run this command: .. code-block:: bash @@ -17,13 +20,12 @@ To render the cheat sheet, run this command: Output ------ -The rendered cheat sheet is saved as ``cheat_sheet.pdf`` in the same directory as the input file. +The rendered cheat sheet is saved as the ``cheat_sheet.pdf`` file in the same directory as the QMD file. -You can download the rendered cheat sheet by clicking the following link: +You can download the PDF file of this cheat sheet by clicking the following link: .. button-link:: _static/cheat_sheet.pdf :ref-type: ref :color: info - :align: center - Rendered PDF :octicon:`download;1em` + Rendered PDF file :octicon:`download;1em` diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index 424c0df..caa5355 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -1,7 +1,67 @@ Getting started =============== -.. include:: ../../README.md - :parser: myst_parser.sphinx_ - :start-after: ## Prerequisites - :end-before: > ## Usage +This section explains how to install PyAnsys Quarto Cheat Sheet. + +Prerequisites +------------- + +Before you can use PyAnsys Quarto Cheat Sheet, you must have Quarto installed. For installation +information, see `Getting Started `_ in +the Quarto documenation. + +Installation +------------ + +You can install PyAnsys Quarto Cheat Sheet from the GitHub repository or from an +archive file. + +Install from the GitHub repository +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +From the GitHub repository, you can install the latest version of PyAnsys Quart Cheat Sheet +from the main branch or install a version from a specific release branch. + +- To install the latest version from the main branch, run this command: + + .. code-block:: bash + + quarto use ansys-internal/pyansys-quarto-cheatsheet@main + + +- To install the version from a specific release branch, rather than using ``@main``, use + the release branch, such as ``@v0.1.0``: + + + .. code-block:: bash + + quarto use ansys-internal/pyansys-quarto-cheatsheet@v0.1.0 + + +Install from an archive file +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To install from an archive file: + +#. Download the ``cheat_sheet.zip`` or ``cheat_sheet.tar.gz`` archive file from the + repository's `Releases `_ + page. + +#. Run the command that installs PyAnsys Quarto Cheat Sheet in the Quarto environment from + the ZIP or TAR.GZ file. + + The command that you run creates an ``_extensions`` directory in the current directory + with all the files for PyAnsys Quarto Cheat Sheet. + + - For a ZIP file, run this command: + + .. code-block:: bash + + quarto use cheat_sheet.zip + + + - For a TAR.GZ file, run this command: + + .. code-block:: bash + + quarto use cheat_sheet.tar.gz diff --git a/doc/source/index.rst b/doc/source/index.rst index e83ee14..78e9494 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,33 +1,35 @@ PyAnsys Quarto Cheat Sheet documentation |version| ================================================== -PyAnsys Quarto Cheat Sheet is an extension for using [Quarto](https://quarto.org/), an open +PyAnsys Quarto Cheat Sheet is an extension for using `Quarto `_, an open source scientific and technical publishing system, to generate cheat sheets from plain text -markdown. +markdown and code. -.. grid:: 1 2 2 2 - :gutter: 3 3 4 4 +.. grid:: 2 .. grid-item-card:: Getting started :fa:`person-running` + :padding: 2 2 2 2 :link: getting-started :link-type: doc Learn how to install PyAnsys Quarto Cheat Sheet. - .. grid-item-card:: User guide :fa:`book-open-reader` + .. grid-item-card:: User guide :fa:`book-open-reader` + :padding: 2 2 2 2 :link: user-guide :link-type: doc - Understand how to use PyAnsys Quarto Cheat Sheet to generate - cheat sheets. + Understand how to use the YAML configuration file for a cheat sheet + to format it. .. grid-item-card:: Examples :fa:`code` + :padding: 2 2 2 2 :link: examples :link-type: doc Explore examples that show how to use PyAnsys Quarto Cheat Sheet to - generate cheat sheets. + create your own cheat sheets. .. toctree:: diff --git a/doc/source/user-guide.rst b/doc/source/user-guide.rst index 0eb511e..46bc0dd 100644 --- a/doc/source/user-guide.rst +++ b/doc/source/user-guide.rst @@ -1,6 +1,131 @@ User guide ========== -.. include:: ../../README.md - :parser: myst_parser.sphinx_ - :start-after: # Usage +To render a cheat sheet as a PDF file, you run a command like this one: + +.. code-block:: bash + + quarto render examples/cheat_sheet.qmd --to cheat_sheet-pdf + + +The preceding command renders the ``cheat_sheet.qmd`` file that is in +the ``Examples`` directory to a PDF file in this same directory. For more +information, see :ref:`cheat_sheet_example`. + +Format options +-------------- + +The YAML configuration file for a cheat sheet specifies format options: + +- ``version``: Version of the cheat sheet:: + + version: 0.1 + +- ``title``: Title of the cheat sheet:: + + title: PyMAPDL cheat sheet + +- ``footer``: Footer text of the cheat sheet:: + + footer: PyMAPDL cheat sheet + +- ``footerlinks``: List of links to display in the footer of the cheat sheet. + Each link must have a ``urls`` and ``text`` option:: + + footerlinks: + - urls: https://mapdl.docs.pyansys.com/version/stable/ + text: PyMAPDL documentation + +- ``format``: Format for rendering the cheat sheet. For PDF generation, use ``cheat_sheet-pdf``:: + + format: cheat_sheet-pdf + +- ``execute``: Controls code and cell output. While descriptions for key options follow, see + `Code Cells: Knitr `_ in the Quarto + documentation for descriptions of all available options. + + - ``eval``: Whether to evaluate code cells. If ``False``, the code is only echoed in the output:: + + execute: + eval: false + + - ``echo``: Whether to include cell source code in the output:: + + execute: + echo: false + + - ``output``: Whether to include the results of executing the code in the output:: + + execute: + output: false + + +Configuration file example +-------------------------- + +Here is an example of a YAML configuration file:: + + version: 0.1 + title: PyMAPDL cheat sheet + footer: PyMAPDL cheat sheet + footerlinks: + - urls: https://mapdl.docs.pyansys.com/version/stable/ + text: PyMAPDL Documentation + format: cheat_sheet-pdf + execute: + eval: false + echo: false + output: false + + +By default, code cells are executed. To disable execution, for the ``execute`` option, +set ``eval: false``. + +To disable execution and exclude the cell source code in the output, +use the ``eval``, ``echo``, and similar options within the code cell:: + + eval: false + echo: false + + +By default, the results of executing the code are included in the output. To exclude these +results, for the ``execute`` option, set ``output: false``. + + +The ``_quarto.yml`` file +------------------------ + +The ``_quarto.yml`` file is a configuration file that contains all the metadata at the project level. +For more information, see the `Project Metadata `_ +in the Quarto documentation. + +If you want to change the output directory, add the following line to the ``_quarto.yml`` file:: + + output_dir: _build + + +The root directory of the repostiory includes an example of a + `_quarto.yml `_ file. + +Other example files +~~~~~~~~~~~~~~~~~~~ + +A Quarto QMD file is a format used for integrating plain text markdown and code into a single +compiled document. The ``Examples`` directory contains these QMD files: + +- The `cheat_sheet.qmd `_ + file is a template that you can use to create your own cheat sheets. +- The `pymapdl_cheat_sheet_example_qmd `_ + file is an example of a PyMAPDL cheat sheet. + +To render the example of a PyMAPDL cheat sheet, run this command:: + + quarto render examples/pymapdl_cheat_sheet_example.qmd + + +.. tip:: + If you want to open a QMD file in Jupyter Notebook, follow these steps: + + #. Install the ``jupytext`` package by running this command: ``pip install jupytext`` + #. Install the ``jupyter`` package by running this command: ``pip install jupyter`` + #. Open the QMD file in Jupyter Notebook by running this command: ``jupyter notebook cheat_sheet.qmd`` diff --git a/examples/cheat_sheet.qmd b/examples/cheat_sheet.qmd index 3a1bf83..7cff05d 100644 --- a/examples/cheat_sheet.qmd +++ b/examples/cheat_sheet.qmd @@ -8,9 +8,9 @@ footerlinks: text: Your text here - urls: Your URL here text: Your text here -# uncommment the following line to not to evaluate code cells +# Uncommment the following line to not evaluate code cells # execute: -# eval: false # Set to true to execute code cells +# eval: false # Set to true to evaluate code cells jupyter: jupytext: text_representation: @@ -26,7 +26,7 @@ jupyter: # General section -Discription of the first section goes here. +Description of the first section goes here. ```{python} import os @@ -34,32 +34,32 @@ import os # Section with code output -Discription of the second section goes here. +Description of the second section goes here. ```{python} -print("Hello World!") +print("Hello, world!") ``` -# Section without code output +# Section with code evaluation but no results included -This section will be evaluated but the output will not be displayed. +This section is evaluated but execution results are not included in the output. ```{python} #| output: false -print("Hello World!") +print("Hello, world!") ``` -# Section with code evaluation without output +# Section with code evaluation but no results included -This section will be evaluated but the output will not be displayed. +This section is evaluated but execution results are not included in the output. ```{python} #| output: false print(os.getcwd()) ``` -# Section with code evaluation and output +# Section with code evaluation and results included -This section will be evaluated and the output will be displayed. +This section is evaluated and execution results are included in the output. ```{python} print(os.getcwd()) @@ -71,31 +71,32 @@ print(os.getcwd()) print(os.getcwd()) ``` -If there is no evaluation, the code cell will not be executed. -So the output will not be displayed. +If there is no evaluation, the code cell is not executed. +Thus, no execution results are included in the output. # Section without code echo -This section will not be evaluated and the code cell will not be displayed on -the rendered document. -But the output will be displayed. +This section is not evaluated, and the code cell is not shown in +the rendered document. However, the output is included in the +rendered document. ```{python} #| echo: false -print("Hello World!") +print("Hello, world!") ``` # Section without code echo and output -This code cell will not be displayed on -the rendered document. -And the output will not be displayed. +This section is not evaluated, and the code cell is not shown in +the rendered document. The output is also not included in the +rendered document. + ```{python} #| echo: false #| output: false -print("Hello World!") +print("Hello, world!") ``` -# use of variables +# Use of variables ## Styles of text @@ -110,9 +111,9 @@ print("Hello World!") 2. Numbered list 3. Numbered list -- Bullet list -- Bullet list -- Bullet list +- Bulleted list +- Bulleted list +- Bulleted list ![image](./../_extensions/cheat_sheet/_static/ansys.png) diff --git a/examples/pymapdl_cheat_sheet_example.qmd b/examples/pymapdl_cheat_sheet_example.qmd index efabc64..cceb413 100644 --- a/examples/pymapdl_cheat_sheet_example.qmd +++ b/examples/pymapdl_cheat_sheet_example.qmd @@ -1,13 +1,13 @@ --- -title: PyMAPDL Cheat sheet +title: PyMAPDL cheat sheet format: cheatsheet-pdf version: 0.1.0 footer: Getting started with PyMAPDL footerlinks: - urls: 'https://mapdl.docs.pyansys.com/version/stable/' - text: PyMAPDL Documentation + text: PyMAPDL documentation - urls: 'https://mapdl.docs.pyansys.com/version/stable/getting_started/index.html' - text: PyMAPDL Documentation getting started + text: PyMAPDL documentation - Getting started execute: # output: false eval: false @@ -220,7 +220,7 @@ mapdl.lplot(vtk=False) ## References from PyMAPDL documentation -- [Getting Started](https://mapdl.docs.pyansys.com/version/stable/getting_started/index.html) +- [Getting started](https://mapdl.docs.pyansys.com/version/stable/getting_started/index.html) - [MAPDL commands](https://mapdl.docs.pyansys.com/version/stable/mapdl_commands/index.html) - [API reference](https://mapdl.docs.pyansys.com/version/stable/api/index.html) From 4deef8c35938945e8f4c20a23f6eb1c1c751fb74 Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 23 Apr 2024 14:52:45 -0400 Subject: [PATCH 03/12] Resolve Vale issues --- doc/source/getting-started.rst | 2 +- doc/source/user-guide.rst | 2 +- doc/styles/config/vocabularies/ANSYS/accept.txt | 5 ++--- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index caa5355..f00b2cb 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -8,7 +8,7 @@ Prerequisites Before you can use PyAnsys Quarto Cheat Sheet, you must have Quarto installed. For installation information, see `Getting Started `_ in -the Quarto documenation. +the Quarto documentation. Installation ------------ diff --git a/doc/source/user-guide.rst b/doc/source/user-guide.rst index 46bc0dd..91a4edf 100644 --- a/doc/source/user-guide.rst +++ b/doc/source/user-guide.rst @@ -104,7 +104,7 @@ If you want to change the output directory, add the following line to the ``_qua output_dir: _build -The root directory of the repostiory includes an example of a +The root directory of the repository includes an example of a `_quarto.yml `_ file. Other example files diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index fa6c6a1..480a6fc 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -1,4 +1,3 @@ (?!)ansys -linenos -eval -disable +Knitr +pymapdl_cheat_sheet_example_qmd \ No newline at end of file From 15d8600a5671e80ab3ba211b8b9849820384e1ec Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 23 Apr 2024 14:56:02 -0400 Subject: [PATCH 04/12] Fix code style issue --- doc/styles/config/vocabularies/ANSYS/accept.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 480a6fc..22cbc58 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -1,3 +1,3 @@ (?!)ansys Knitr -pymapdl_cheat_sheet_example_qmd \ No newline at end of file +pymapdl_cheat_sheet_example_qmd From 495d8aee673766b57fb354dc1284332259d7fb2b Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Tue, 23 Apr 2024 15:25:36 -0400 Subject: [PATCH 05/12] Add "disable" back to Vale's accept list --- doc/styles/config/vocabularies/ANSYS/accept.txt | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/styles/config/vocabularies/ANSYS/accept.txt b/doc/styles/config/vocabularies/ANSYS/accept.txt index 22cbc58..dc02134 100644 --- a/doc/styles/config/vocabularies/ANSYS/accept.txt +++ b/doc/styles/config/vocabularies/ANSYS/accept.txt @@ -1,3 +1,4 @@ (?!)ansys +disable Knitr pymapdl_cheat_sheet_example_qmd From 8b07b85fd48b101a29cc2d08b321eefdcb449a34 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 24 Apr 2024 11:57:50 +0200 Subject: [PATCH 06/12] fix: update the readme and pdf links in example --- README.rst | 10 +--------- doc/source/examples.rst | 3 +-- 2 files changed, 2 insertions(+), 11 deletions(-) diff --git a/README.rst b/README.rst index 712ad37..84f6ca5 100644 --- a/README.rst +++ b/README.rst @@ -1,19 +1,11 @@ PyAnsys Quarto Cheat Sheet ========================== -|pyansys| |python| |pypi| |GH-CI| |MIT| +|pyansys| |GH-CI| |MIT| .. |pyansys| image:: https://img.shields.io/badge/Py-Ansys-ffc107.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAABDklEQVQ4jWNgoDfg5mD8vE7q/3bpVyskbW0sMRUwofHD7Dh5OBkZGBgW7/3W2tZpa2tLQEOyOzeEsfumlK2tbVpaGj4N6jIs1lpsDAwMJ278sveMY2BgCA0NFRISwqkhyQ1q/Nyd3zg4OBgYGNjZ2ePi4rB5loGBhZnhxTLJ/9ulv26Q4uVk1NXV/f///////69du4Zdg78lx//t0v+3S88rFISInD59GqIH2esIJ8G9O2/XVwhjzpw5EAam1xkkBJn/bJX+v1365hxxuCAfH9+3b9/+////48cPuNehNsS7cDEzMTAwMMzb+Q2u4dOnT2vWrMHu9ZtzxP9vl/69RVpCkBlZ3N7enoDXBwEAAA+YYitOilMVAAAAAElFTkSuQmCC :target: https://docs.pyansys.com/ :alt: PyAnsys -.. |python| image:: https://img.shields.io/pypi/pyversions/urlinclude?logo=pypi - :target: https://pypi.org/project/urlinclude/ - :alt: Python - -.. |pypi| image:: https://img.shields.io/pypi/v/urlinclude.svg?logo=python&logoColor=white - :target: https://pypi.org/project/urlinclude - :alt: PyPI - .. |GH-CI| image:: https://github.com/ansys-internal/pyansys-quarto-cheatsheet/actions/workflows/ci_cd.yml/badge.svg :target: https://github.com/ansys-internal/pyansys-quarto-cheatsheet/actions/workflows/ci_cd.yml :alt: GH-CI diff --git a/doc/source/examples.rst b/doc/source/examples.rst index b7982a3..a21d8de 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -24,8 +24,7 @@ The rendered cheat sheet is saved as the ``cheat_sheet.pdf`` file in the same di You can download the PDF file of this cheat sheet by clicking the following link: -.. button-link:: _static/cheat_sheet.pdf - :ref-type: ref +.. button-link:: https://quarto-cheat-sheet.docs.pyansys.com/version/dev/_static/cheat_sheet.pdf :color: info Rendered PDF file :octicon:`download;1em` From 7bcc9aa196ea080d8470194c04bd9062a231a68a Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 24 Apr 2024 16:15:02 +0200 Subject: [PATCH 07/12] docs: updated the example pdf --- doc/source/examples.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/source/examples.rst b/doc/source/examples.rst index a21d8de..8a0388a 100644 --- a/doc/source/examples.rst +++ b/doc/source/examples.rst @@ -22,9 +22,11 @@ Output The rendered cheat sheet is saved as the ``cheat_sheet.pdf`` file in the same directory as the QMD file. -You can download the PDF file of this cheat sheet by clicking the following link: +You can view a PDF file with the content originally provided in this cheat sheet by clicking the following link. +If you have run the preceding command, you can open the PDF saved in the ``Examples`` directory. +This PDF includes any changes that you might have made to the ``cheat_sheet.qmd`` file. .. button-link:: https://quarto-cheat-sheet.docs.pyansys.com/version/dev/_static/cheat_sheet.pdf :color: info - Rendered PDF file :octicon:`download;1em` + Rendered PDF file :octicon:`eye;1em` From f762920f9e46a6bfe11e23271fabe3cecde7c855 Mon Sep 17 00:00:00 2001 From: Revathy Venugopal <104772255+Revathyvenugopal162@users.noreply.github.com> Date: Wed, 24 Apr 2024 17:14:55 +0200 Subject: [PATCH 08/12] Update doc/source/user-guide.rst --- doc/source/user-guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/user-guide.rst b/doc/source/user-guide.rst index 91a4edf..d199119 100644 --- a/doc/source/user-guide.rst +++ b/doc/source/user-guide.rst @@ -84,8 +84,8 @@ set ``eval: false``. To disable execution and exclude the cell source code in the output, use the ``eval``, ``echo``, and similar options within the code cell:: - eval: false - echo: false + #| eval: false + #| echo: false By default, the results of executing the code are included in the output. To exclude these From 5ce9fe56c3ae53bf25ad697ebb21d30729a2eab6 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Wed, 24 Apr 2024 17:41:19 +0200 Subject: [PATCH 09/12] docs: add contributing section --- doc/source/contributing.rst | 125 ++++++++++++++++++++++++++++++++++++ doc/source/index.rst | 8 +++ 2 files changed, 133 insertions(+) create mode 100644 doc/source/contributing.rst diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..31c90b7 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,125 @@ +Contribute +########## + +Overall guidance on contributing to a PyAnsys library appears in the +`Contributing `_ topic +in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar +with this guide before attempting to contribute to PyAnsys Quarto Cheat Sheet. + +The following contribution information is specific to PyAnsys Quarto Cheat Sheet. + +Clone the repository +-------------------- + +To clone and install the latest PyAnsys Quarto Cheat Sheet in development mode, run +these commands: + +.. code:: + + git clone https://github.com/ansys-internal/pyansys-quarto-cheatsheet.git + cd pyansys-quarto-cheatsheet + + # Install the package in development mode + quarto install extension . --no-prompt + + +Post issues +----------- + +Use the `PyAnsys Quarto Cheat Sheet Issues `_ +page to submit questions, report bugs, and request new features. + +To reach the project support team, email `pyansys.core@ansys.com `_. + +View documentation +------------------ + +Documentation for the latest stable release of PyAnsys Quarto Cheat Sheet is hosted at +`PyAnsys Quarto Cheat Sheet Documentation `_. + +In the upper right corner of the documentation's title bar, there is an option +for switching from viewing the documentation for the latest stable release +to viewing the documentation for the development version or previously +released versions. + +Adhere to code style +-------------------- + +PyAnsys Quarto Cheat Sheet implements style checking using +`pre-commit `_. + +To ensure your code meets minimum code styling standards, run these commands:: + + pip install pre-commit + pre-commit run --all-files + +You can also install this as a pre-commit hook by running this command:: + + pre-commit install + +This way, it's not possible for you to push code that fails the style checks:: + + $ pre-commit install + $ git commit -am "feat: Added my cool features" + check yaml...............................................................Passed + trim trailing whitespace.................................................Passed + fix end of files.........................................................Passed + check for merge conflicts................................................Passed + Validate GitHub Workflows................................................Passed + Add License Headers......................................................Passed + + +Build the cheat sheet +--------------------- +.. note:: + + To build cheat sheet PDF locally, you must have `quarto `_ installed. + +To build the cheat sheet PDF, run this command:: + + quarto render cheatsheet.qmd + +The cheat sheet PDF is built in the ``_build`` directory +since the output directory is set to ``_build`` in the ``_quarto.yml`` file. +if you want to change the output directory, you can change it in the ``_quarto.yml`` file. + +Build the documentation +----------------------- +To build the documentation locally, you must run this command to install the +documentation dependencies in requirements_docs.txt in requirements directory:: + + pip install -r requirements/requirements_docs.txt + +Then, navigate to the ``doc`` directory and run this command + +.. tab-set:: + + .. tab-item:: Linux/macOS + + .. code:: + + make html + + .. tab-item:: Windows + + .. code:: + + ./make.bat html + +The documentation is built in the ``doc/_build/html`` directory. + +You can clean the documentation build by running this command + +.. tab-set:: + + .. tab-item:: Linux/macOS + + .. code:: + + make clean + + .. tab-item:: Windows + + .. code:: + + ./make.bat clean diff --git a/doc/source/index.rst b/doc/source/index.rst index 78e9494..a1ae717 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -31,6 +31,13 @@ markdown and code. Explore examples that show how to use PyAnsys Quarto Cheat Sheet to create your own cheat sheets. + .. grid-item-card:: Contributing :fa:`users` + :padding: 2 2 2 2 + :link: contributing + :link-type: doc + + Learn how to contribute to the development of PyAnsys Quarto Cheat Sheet. + .. toctree:: :hidden: @@ -38,3 +45,4 @@ markdown and code. getting-started user-guide examples + contributing From 56046daae4068e90591d4d7d6309df30d3aacedc Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 25 Apr 2024 14:16:21 +0200 Subject: [PATCH 10/12] docs: update the heading --- doc/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/index.rst b/doc/source/index.rst index a1ae717..d311077 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,4 +1,4 @@ -PyAnsys Quarto Cheat Sheet documentation |version| +PyAnsys quarto cheat sheet documentation |version| ================================================== PyAnsys Quarto Cheat Sheet is an extension for using `Quarto `_, an open From e2f9aa88a76a8be099933d7355da6aae5b4d90d3 Mon Sep 17 00:00:00 2001 From: Revathyvenugopal162 Date: Thu, 25 Apr 2024 14:28:20 +0200 Subject: [PATCH 11/12] docs: update the contribute --- README.rst | 8 +++++--- doc/source/contributing.rst | 8 ++++---- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/README.rst b/README.rst index 84f6ca5..25bb504 100644 --- a/README.rst +++ b/README.rst @@ -30,12 +30,14 @@ at `PyAnsys Quarto Cheat Sheet documentation `_: Learn +- `Getting started `_: Learn how to install PyAnsys Quarto Cheat Sheet. -- `User guide `_: Understand how +- `User guide `_: Understand how to use the YAML configuration file for a cheat sheet to format it. -- `Examples `_: Explore examples +- `Examples `_: Explore examples that show how to use PyAnsys Quarto Cheat Sheet to create your own cheat sheets. +- `Contribute `_: Learn how to + contribute to PyAnsys Quarto Cheat Sheet. In the upper right corner of the documentation's title bar, there is an option for switching from viewing the documentation for the latest stable release diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 31c90b7..304ce66 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -73,11 +73,11 @@ Build the cheat sheet --------------------- .. note:: - To build cheat sheet PDF locally, you must have `quarto `_ installed. + To build cheat sheet PDF locally, you must have `quarto `_ installed. To build the cheat sheet PDF, run this command:: - quarto render cheatsheet.qmd + quarto render examples/cheat_sheet.qmd The cheat sheet PDF is built in the ``_build`` directory since the output directory is set to ``_build`` in the ``_quarto.yml`` file. @@ -88,7 +88,7 @@ Build the documentation To build the documentation locally, you must run this command to install the documentation dependencies in requirements_docs.txt in requirements directory:: - pip install -r requirements/requirements_docs.txt + pip install -r requirements/requirements_doc.txt Then, navigate to the ``doc`` directory and run this command @@ -108,7 +108,7 @@ Then, navigate to the ``doc`` directory and run this command The documentation is built in the ``doc/_build/html`` directory. -You can clean the documentation build by running this command +You can clean the documentation build by running this command: .. tab-set:: From 39f0bd2a44864eaf771ea9c468b95baae34d55fb Mon Sep 17 00:00:00 2001 From: Kathy Pippert Date: Thu, 25 Apr 2024 11:40:43 -0400 Subject: [PATCH 12/12] Edits to contributing.rst and for where PDF files of cheat sheets are saved to --- README.rst | 8 ++-- doc/source/contributing.rst | 70 +++++++++++++++++----------------- doc/source/getting-started.rst | 4 +- doc/source/index.rst | 11 +++--- doc/source/user-guide.rst | 24 ++++++------ 5 files changed, 62 insertions(+), 55 deletions(-) diff --git a/README.rst b/README.rst index 25bb504..5b45e50 100644 --- a/README.rst +++ b/README.rst @@ -31,13 +31,13 @@ at `PyAnsys Quarto Cheat Sheet documentation `_: Learn - how to install PyAnsys Quarto Cheat Sheet. + how to install PyAnsys Quarto Cheat Sheet in user mode. - `User guide `_: Understand how - to use the YAML configuration file for a cheat sheet to format it. + to render a PDF file of a cheat sheet and use its YAML configuration file to format it. - `Examples `_: Explore examples - that show how to use PyAnsys Quarto Cheat Sheet to create your own cheat sheets. + that show how to use PyAnsys Quarto Cheat Sheet to create and render your own cheat sheets. - `Contribute `_: Learn how to - contribute to PyAnsys Quarto Cheat Sheet. + contribute to the PyAnsys Quarto Cheat Sheet codebase or documentation. In the upper right corner of the documentation's title bar, there is an option for switching from viewing the documentation for the latest stable release diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 304ce66..58242e3 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,18 +1,23 @@ +.. _contribute: + Contribute ########## Overall guidance on contributing to a PyAnsys library appears in the `Contributing `_ topic -in the *PyAnsys Developer's Guide*. Ensure that you are thoroughly familiar +in the *PyAnsys developer's guide*. Ensure that you are thoroughly familiar with this guide before attempting to contribute to PyAnsys Quarto Cheat Sheet. The following contribution information is specific to PyAnsys Quarto Cheat Sheet. -Clone the repository --------------------- +Install in developer mode +------------------------- + +Installing PyAnsys Quarto Cheat Sheet in developer mode allows you to modify +and enhance the source. -To clone and install the latest PyAnsys Quarto Cheat Sheet in development mode, run -these commands: +To clone and install the latest version of PyAnsys Quarto Cheat Sheet in +development mode, run these commands: .. code:: @@ -23,29 +28,12 @@ these commands: quarto install extension . --no-prompt -Post issues ------------ - -Use the `PyAnsys Quarto Cheat Sheet Issues `_ -page to submit questions, report bugs, and request new features. - -To reach the project support team, email `pyansys.core@ansys.com `_. - -View documentation ------------------- - -Documentation for the latest stable release of PyAnsys Quarto Cheat Sheet is hosted at -`PyAnsys Quarto Cheat Sheet Documentation `_. - -In the upper right corner of the documentation's title bar, there is an option -for switching from viewing the documentation for the latest stable release -to viewing the documentation for the development version or previously -released versions. - Adhere to code style -------------------- -PyAnsys Quarto Cheat Sheet implements style checking using +PyAnsys Quarto Cheat Sheet follows the PEP8 standard as outlined in +`PEP 8 `_ in +the *PyAnsys developer's guide* and implements style checking using `pre-commit `_. To ensure your code meets minimum code styling standards, run these commands:: @@ -68,25 +56,28 @@ This way, it's not possible for you to push code that fails the style checks:: Validate GitHub Workflows................................................Passed Add License Headers......................................................Passed - -Build the cheat sheet ---------------------- +Render a cheat sheet +-------------------- .. note:: - To build cheat sheet PDF locally, you must have `quarto `_ installed. + To render a cheat sheet to a PDF file locally, you must have Quarto installed. For + installation information, see `Getting Started `_ + in the Quarto documentation. -To build the cheat sheet PDF, run this command:: +To render a cheat sheet to a PDF file, run a command like this one:: quarto render examples/cheat_sheet.qmd -The cheat sheet PDF is built in the ``_build`` directory -since the output directory is set to ``_build`` in the ``_quarto.yml`` file. -if you want to change the output directory, you can change it in the ``_quarto.yml`` file. +The preceding command saves the PDF file for the ``cheat_sheet.qmd`` file in +the ``Examples`` directory to the ``doc/_build`` directory by default. If you +want to change the output directory, you can modify the ``_quarto.yml`` file. +For more information, see :ref:`quarto-yml`. Build the documentation ----------------------- To build the documentation locally, you must run this command to install the -documentation dependencies in requirements_docs.txt in requirements directory:: +documentation dependencies in the ``requirements_docs.txt`` file in the ``requirements`` +directory:: pip install -r requirements/requirements_doc.txt @@ -123,3 +114,14 @@ You can clean the documentation build by running this command: .. code:: ./make.bat clean + +Post issues +----------- + +Use the `PyAnsys Quarto Cheat Sheet Issues `_ +page to report bugs and request new features. When possible, use the issue templates provided. +If your issue does not fit into one of these templates, click the link for opening a blank issue. + +If you have general questions about the PyAnsys ecosystem, email `pyansys.core@ansys.com `_. +If your question is specific to PyAnsys Quarto Cheat Sheet, ask your question in an issue as described +in the previous paragraph. diff --git a/doc/source/getting-started.rst b/doc/source/getting-started.rst index f00b2cb..64022f1 100644 --- a/doc/source/getting-started.rst +++ b/doc/source/getting-started.rst @@ -1,7 +1,9 @@ Getting started =============== -This section explains how to install PyAnsys Quarto Cheat Sheet. +This section explains how to install PyAnsys Quarto Cheat Sheet in user mode. If you are +interested in contributing to PyAnsys Quarto Cheat Sheet, see :ref:`contribute` for information +on installing in developer mode. Prerequisites ------------- diff --git a/doc/source/index.rst b/doc/source/index.rst index d311077..3ed2260 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -13,15 +13,15 @@ markdown and code. :link: getting-started :link-type: doc - Learn how to install PyAnsys Quarto Cheat Sheet. + Learn how to install PyAnsys Quarto Cheat Sheet in user mode. .. grid-item-card:: User guide :fa:`book-open-reader` :padding: 2 2 2 2 :link: user-guide :link-type: doc - Understand how to use the YAML configuration file for a cheat sheet - to format it. + Understand how to render a PDF file of a cheat sheet and use its + YAML configuration file to format it. .. grid-item-card:: Examples :fa:`code` :padding: 2 2 2 2 @@ -29,14 +29,15 @@ markdown and code. :link-type: doc Explore examples that show how to use PyAnsys Quarto Cheat Sheet to - create your own cheat sheets. + create and render your own cheat sheets. .. grid-item-card:: Contributing :fa:`users` :padding: 2 2 2 2 :link: contributing :link-type: doc - Learn how to contribute to the development of PyAnsys Quarto Cheat Sheet. + Learn how to contribute to the PyAnsys Quarto Cheat Sheet codebase + or documentation. .. toctree:: diff --git a/doc/source/user-guide.rst b/doc/source/user-guide.rst index d199119..1eb6aa9 100644 --- a/doc/source/user-guide.rst +++ b/doc/source/user-guide.rst @@ -1,16 +1,17 @@ User guide ========== -To render a cheat sheet as a PDF file, you run a command like this one: +To render a cheat sheet to a PDF file locally, you run a command like this one: .. code-block:: bash quarto render examples/cheat_sheet.qmd --to cheat_sheet-pdf -The preceding command renders the ``cheat_sheet.qmd`` file that is in -the ``Examples`` directory to a PDF file in this same directory. For more -information, see :ref:`cheat_sheet_example`. +The preceding command saves the PDF file for the ``cheat_sheet.qmd`` file in +the ``Examples`` directory to the ``doc/_build`` directory by default. If +you want to change the output directory, you can modify the ``_quarto.yml`` +file. For more information, see :ref:`quarto-yml`. Format options -------------- @@ -91,21 +92,22 @@ use the ``eval``, ``echo``, and similar options within the code cell:: By default, the results of executing the code are included in the output. To exclude these results, for the ``execute`` option, set ``output: false``. +.. _quarto-yml: The ``_quarto.yml`` file ------------------------ -The ``_quarto.yml`` file is a configuration file that contains all the metadata at the project level. -For more information, see the `Project Metadata `_ -in the Quarto documentation. +As indicated in `Project Metadata `_ +in the Quarto documentation, all Quarto projects include a ``_quarto.yml`` configuration file. Any document +rendered within the project directory automatically inherit the metadata defined at the project level. -If you want to change the output directory, add the following line to the ``_quarto.yml`` file:: +The root directory of the PyAnsys Cheat Sheet repository includes an example of a + `_quarto.yml `_ file. - output_dir: _build +To change the directory that PDF files for cheat sheets are saved to, you would modify this line:: + latex-output-dir: _build -The root directory of the repository includes an example of a - `_quarto.yml `_ file. Other example files ~~~~~~~~~~~~~~~~~~~