diff --git a/doc/source/library_description/template.rst b/doc/source/library_description/template.rst index 402a53f64..56d60facb 100644 --- a/doc/source/library_description/template.rst +++ b/doc/source/library_description/template.rst @@ -2,21 +2,88 @@ Library Template ################ -Within the `PyAnsys Organization `_, there -is a `template repository `_ -where you can `create a repository from a template`_ and create a -PyAnsys project that follows the guidelines specified in this developer's -guide. +Starting a new project from scratch is a tedious task. For this reason, the +`ansys-templates`_ tool was created to simplify the starting process and +make it more dynamic. Any rendered project will be compliant with the latest +PyAnsys coding and API style guidelines. -The template repository contains a generalized library skeleton that includes: +The ansys-templates tool +======================== -- Library skeleton with sample classes and methods -- Sample documentation build including customized templates -- Sample GitHub actions specific to PyAnsys libraries -- Licensing, example README, and setup files -- ``.gitignore`` and other requirements files +The `ansys-templates`_ is a command line interface which provides you with a +collection of templates. This tool allows you to create new PyAnsys projects +from scratch in a dynamic way by asking you several questions before generating +the new project. -To use this template, `create a repository from a template`_. +Please, follow the `ansys-templates installation guide`_ to get the latest stable +version installed in your system. +- **Repository**: https://github.com/pyansys/pyansys-templates +- **Documentation**: https://github.com/pyansys/pyansys-templates +- **Issues board**: https://github.com/pyansys/pyansys-templates/issues -.. _Create a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template + +.. note:: + + Open a new issue in the `ansys-templates issues board`_ if you encounter any + problem during the installation or usage of the tool. + + +PyAnsys Available Templates +=========================== + +There are two templates which can be used as basis for creating new PyAnsys +projects. These are the ``pyansys`` and the ``pyansys-advanced`` templates. + +.. important:: + + Install `ansys-templates`_ to access these templates. Refer to the + `ansys-templates user guide`_ for more information on how to use this tool. + + +PyAnsys Template +---------------- + +The ``pyansys`` template ships only with the required directories and files to +quickly setup a PyAnsys compliant project: + +- Provides a ``src/ansys/product/library/`` layout +- Includes a ``setup.py`` file +- Generates a ``doc/`` and a ``tests/`` directories +- Generic ``.gitignore`` for Python libraries +- Includes building, doc, and test requirements files +- Metadata files like ``README.rst`` and ``LICENSE`` + +Create a new project based on the ``pyansys`` template by running: + +.. code:: bash + + ansys-templates new pyansys + + +PyAnsys Advanced Template +------------------------- + +The ``pyansys-advanced`` is an enhanced version of the ``pyansys`` template. It +ships with the same files as this last template except: + +- Allows you to select the project file (``setup.py`` or ``pyproject.toml``) +- Uses `Tox`_ for testing and tasks automation +- Includes GitHub actions for CI purposes +- Uses `pre-commit`_ for checking coding style + +Create a new project based on the ``pyansys-advanced`` template by running: + +.. code:: bash + + ansys-templates new pyansys-advanced + +.. _ansys-templates: https://templates.pyansys.com/index.html +.. _ansys-templates installation guide: https://templates.pyansys.com/getting_started/index.html +.. _ansys-templates user guide: https://templates.pyansys.com/user_guide/index.html +.. _ansys-templates issues board: https://github.com/pyansys/pyansys-templates/issues +.. _flit: https://flit.readthedocs.io/en/latest/ +.. _poetry: https://python-poetry.org/ +.. _pre-commit: https://pre-commit.com/ +.. _setuptools: https://pypi.org/project/setuptools/ +.. _Tox: https://tox.wiki/en/latest/