Doc/overall review

README.rst

@@ -0,0 +1,62 @@
+PyAnsys Quarto Cheat Sheet
+==========================
+|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
+
+.. |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 <https://quarto.org/>`_, 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 <https://quarto-cheat-sheet.docs.pyansys.com/>`_.
+
+The documentation has these sections:
+
+- `Getting started <https://quarto-cheat-sheet.docs.pyansys.com/version/dev/getting_started.html>`_: Learn
+  how to install PyAnsys Quarto Cheat Sheet in user mode.
+- `User guide <https://quarto-cheat-sheet.docs.pyansys.com/version/dev/user_guide.html>`_: Understand how
+  to render a PDF file of a cheat sheet and use its YAML configuration file to format it.
+- `Examples <https://quarto-cheat-sheet.docs.pyansys.com/version/dev/examples.html>`_: Explore examples
+  that show how to use PyAnsys Quarto Cheat Sheet to create and render your own cheat sheets.
+- `Contribute <https://quarto-cheat-sheet.docs.pyansys.com/version/dev/contributing.html>`_: Learn how to
+  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
+to viewing the documentation for the development version or previously
+released versions.
+
+On the `PyAnsys Quarto Cheat Sheet Issues <https://github.com/ansys-internal/pyansys-quarto-cheatsheet/issues>`_
+page, you can create issues to report bugs and request new features. On the
+`Discussions <https://discuss.ansys.com/>`_ 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 <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 <https://github.com/ansys-internal/pyansys-quarto-cheatsheet/blob/main/LICENSE>`_.
+
+PyAnsys Quarto Cheat Sheet makes no commercial claim over Ansys whatsoever.

doc/.vale.ini

@@ -27,5 +27,3 @@ Vale.Terms = NO
 
 # Apply the following styles
 BasedOnStyles = Vale, Google
-
-Google.Headings = NO

doc/source/contributing.rst

@@ -0,0 +1,127 @@
+.. _contribute:
+
+Contribute
+##########
+
+Overall guidance on contributing to a PyAnsys library appears in the
+`Contributing <https://dev.docs.pyansys.com/how-to/contributing.html>`_ 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.
+
+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 version of 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
+
+
+Adhere to code style
+--------------------
+
+PyAnsys Quarto Cheat Sheet follows the PEP8 standard as outlined in
+`PEP 8 <https://dev.docs.pyansys.com/coding-style/pep8.html>`_ in
+the *PyAnsys developer's guide* and implements style checking using
+`pre-commit <https://pre-commit.com/>`_.
+
+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
+
+Render a cheat sheet
+--------------------
+.. note::
+
+  To render a cheat sheet to a PDF file locally, you must have Quarto installed. For
+  installation information, see `Getting Started <https://quarto.org/docs/getting-started/installation.html>`_
+  in the Quarto documentation.
+
+To render a cheat sheet to a PDF file, run a command like this one::
+
+  quarto render examples/cheat_sheet.qmd
+
+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 the ``requirements_docs.txt`` file in the ``requirements``
+directory::
+
+  pip install -r requirements/requirements_doc.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
+
+Post issues
+-----------
+
+Use the `PyAnsys Quarto Cheat Sheet Issues <https://github.com/ansys-internal/pyansys-quarto-cheatsheet/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 <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.

doc/source/examples.rst

@@ -1,13 +1,16 @@
+.. _cheat_sheet_example:
+
 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 `cheat_sheet.qmd <https://github.com/ansys-internal/pyansys-quarto-cheatsheet/blob/main/examples/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 the following 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,13 @@ To render the cheat sheet, run the following 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.
 
-The rendered cheat sheet can be downloaded by clicking the link below:
+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:: _static/cheat_sheet.pdf
-    :ref-type: ref
+.. button-link:: https://quarto-cheat-sheet.docs.pyansys.com/version/dev/_static/cheat_sheet.pdf
     :color: info
-    :align: center
 
-    Rendered pdf :octicon:`download;1em`
+    Rendered PDF file :octicon:`eye;1em`