Set up doc for Ansys Sphinx theme like PyAnsys libraries (#103)

* Set up doc for Ansys Sphinx theme like PyAnsys libraries

* Fix missing config file and clean up based on rendering

* Apply suggestions from code review

Incorporate Roberto's feedback

Co-authored-by: Roberto Pastor Muela <roberto.pastormuela@ansys.com>

* Update doc/source/User_guide/options.rst

Incorporate missed change.

Co-authored-by: Roberto Pastor Muela <roberto.pastormuela@ansys.com>

* Add "boolean" to accept.txt

Google style guide:
When referring to the abstract data type, use lowercase. (In the unlikely event that you refer to Boolean mathematics or Boolean logic, use uppercase.)

* Renaming folders

Co-authored-by: RobPasMue <roberto.pastormuela@ansys.com>

README.rst

@@ -33,8 +33,8 @@ The Ansys Sphinx theme is an extension of the popular
 `PyData Sphinx theme <https://github.com/pydata/pydata-sphinx-theme>`_ 
 that is used by `numpy <https://numpy.org/doc/stable/>`_,
 `pandas <https://pandas.pydata.org/docs/>`_,
-`PyVista <https://docs.pyvista.org>`_, and many other
-packages.
+`pyvista <https://docs.pyvista.org>`_, and many more
+scientific Python packages.
 
 You use the Ansys Sphinx theme with `Sphinx <https://www.sphinx-doc.org/en/master/>`_,
 a Python documentation generator, to create documentation.

doc/source/getting_started/index.rst

@@ -0,0 +1,36 @@
+.. _ref_getting_started:
+
+===============
+Getting started
+===============
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_ is a Python documentation
+generator for creating documentation. If you are new to using Sphinx, see
+`Sphinx Getting Started <https://www.sphinx-doc.org/en/master/usage/quickstart.html>`_.
+
+This section explains how to install the Ansys Sphinx theme and then set up your
+Sphinx ``conf.py`` file to use this theme to generate your documentation.
+
+Install the theme
+-----------------
+Install the Ansys Sphinx theme with:
+
+.. code::
+
+   pip install ansys-sphinx-theme
+
+Modify the ``conf.py`` file
+---------------------------
+To use this theme, modify your Sphinx ``conf.py`` file::
+
+   html_theme ='ansys_sphinx_theme'
+
+Consider using the ``conf.py`` for this repository:
+
+.. literalinclude:: ../conf.py
+   :language: python
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+

doc/source/index.rst

@@ -9,10 +9,6 @@ Ansys Sphinx Theme documentation |version|
    :hidden:
    :maxdepth: 3
 
-   installation
-   css
-   options
-   404_page
-
-
+   getting_started/index.rst
+   user_guide/index.rst
 

doc/source/404_page.rst → doc/source/user_guide/404_page.rst

@@ -1,15 +1,17 @@
-*********
-404 pages
-*********
+.. _ref_user_guide_404_page:
+
+********
+404 page
+********
 Because Sphinx does not create a 404 page by default, you can use the
 `sphinx-notfound-page
 <https://sphinx-notfound-page.readthedocs.io/en/latest/index.html>`_ extension
 for 404 pages. While originally developed to be used with `Read the Docs <https://readthedocs.org/>`_,
 this extension can be used in other hosting services. For more
 information, see the extension's `documentation <https://sphinx-notfound-page.readthedocs.io/en/latest/how-it-works.html>`_. 
 
-Installation 
-------------
+Install the extension
+---------------------
 Install and enable the ``sphinx-notfound-page`` extension with:
 
 .. code-block:: text
@@ -18,8 +20,8 @@ Install and enable the ``sphinx-notfound-page`` extension with:
 
 Consider adding this extension to your ``requirements_doc.txt`` file.
 
-Configuration
--------------
+Add the extension to the ``conf.py`` file
+-----------------------------------------
 After installing the ``sphinx-notfound-page`` extension, add it to
 your ``conf.py`` file:
 
@@ -37,10 +39,14 @@ your ``conf.py`` file:
         "contact_mail": "pyansys.support@ansys.com",
     }
 
-Default 404 page
-----------------
-To use the default 404 page that the ``ansys-sphinx-theme`` package supplies,
-add the following lines in ``conf.py``:
+Configure your 404 page
+-----------------------
+You can use the default 404 page that the ``ansys-sphinx-theme`` package supplies
+or create and use a custom 404 page. 
+
+Use the default 404 page
+~~~~~~~~~~~~~~~~~~~~~~~~
+To use the default 404 page, add the following lines in the ``conf.py`` file:
 
 .. code-block:: 
 
@@ -52,25 +58,26 @@ add the following lines in ``conf.py``:
 
 .. _sphinx-notfound-page: https://sphinx-notfound-page.readthedocs.io/en/latest/index.html
 
-Custom 404 page
----------------
-To create a custom 404 page for your project, start by creating a ``404.rst``
-file next to the ``conf.py`` file. Make sure you include the ``:orphan:`` attribute
-at the top of this ``404.rst`` file to suppress the spurious ``document isn't
-included in any toctree`` Sphinx warning.
-
-.. code-block:: rst
-
-    :orphan:
-    
-    Error 404 Not Found
-    ===================
-    The page you are requesting does not exist.
-
-Update the ``notfound_template`` variable in the ``conf.py`` to the location of your
-``404.rst`` file:
-
-.. code-block:: rst
-
-    # Configure sphinx-notfound-page
-    notfound_template = "path/to/404.rst"
+Create and use a custom 404 page
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+To create and use a custom 404 page, do the following:
+
+#. Create a ``404.rst`` file next to the ``conf.py`` file.
+#. To suppress the spurious ``document isn't included in any toctree`` Sphinx
+   warning, include the ``:orphan:`` attribute at the top of this ``404.rst`` file:
+
+   .. code-block:: rst
+
+        :orphan:
+        
+        Error 404 Not Found
+        ===================
+        The page you are requesting does not exist.
+
+#. Update the ``notfound_template`` variable in the ``conf.py`` to the location of
+   your ``404.rst`` file:
+
+   .. code-block:: rst
+
+        # Configure sphinx-notfound-page
+        notfound_template = "path/to/404.rst"

doc/source/css.rst → doc/source/user_guide/css.rst

@@ -1,15 +1,16 @@
-***
+.. _ref_user_guide_css:
+
 CSS
-***
+---
 If you need to edit or append to the CSS for the Ansys Sphinx theme,
 create a directory named ``_static/css`` next to your ``conf.py`` file and
 then create a ``custom.css`` file in this directory.
 
 In this file, place the code for editing or appending to the CSS.
-CSS styles in the ``custom.css`` file override CSS styles for the
+CSS styles in the ``custom.css`` file override the CSS styles in the
 Ansys Sphinx theme.
 
-Here is an example that edits the ``body`` CSS style:
+Here is an example that edits the ``body`` element:
 
 .. code::
 

doc/source/user_guide/index.rst

@@ -0,0 +1,25 @@
+.. _ref_user_guide:
+
+==========
+User guide
+==========
+The Ansys Sphinx theme is based on the `PyData Sphinx theme <https://github.com/pydata/pydata-sphinx-theme>`_.
+For more information on its configuration, see
+`Configuration <https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/configuring.html>`_.
+
+While the Ansys Sphinx theme is often used as is, you can customize the following:
+
+- :ref:`ref_user_guide_css`
+- :ref:`ref_user_guide_html_theme`
+- :ref:`ref_user_guide_pdf_cover`
+- :ref:`ref_user_guide_404_page`
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   css
+   options
+   pdf
+   404_page
+