diff --git a/doc/source/abstraction/app_interface_abstraction.rst b/doc/source/abstraction/app_interface_abstraction.rst index 408773b7c..57398ac85 100644 --- a/doc/source/abstraction/app_interface_abstraction.rst +++ b/doc/source/abstraction/app_interface_abstraction.rst @@ -9,7 +9,7 @@ that is structured around data represented as classes and methods. PyAnsys seeks to make the API a "first class citizen" in regard to interacting with an Ansys product by presenting the product as a stateful data model. Consider the following comparison between using a -recorded script from AEDT versus using the PyAEDT libary to create an +recorded script from AEDT versus using the PyAEDT library to create an open region in the active editor: +------------------------------------------------------+----------------------------------------------+ diff --git a/doc/source/coding_style/best_practices.rst b/doc/source/coding_style/best_practices.rst index 0393d33d6..90875c706 100644 --- a/doc/source/coding_style/best_practices.rst +++ b/doc/source/coding_style/best_practices.rst @@ -3,7 +3,7 @@ Best Practices ============== The following sections summarize the key points from `PEP8`_ and how -they apply to PyAnsys libaries. The goal is for PyAnsys libraries to +they apply to PyAnsys libraries. The goal is for PyAnsys libraries to be consistent in style and formatting with the "big three" data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. diff --git a/doc/source/coding_style/flake8.rst b/doc/source/coding_style/flake8.rst index 6b75620f2..1b64abaf2 100644 --- a/doc/source/coding_style/flake8.rst +++ b/doc/source/coding_style/flake8.rst @@ -70,7 +70,7 @@ The above configuration defines the following options: This denotes the maximum line length for any one line of code. The `PEP8`_ standard advises a maximum line length of 79. Because this is a bit limiting in some cases, the maximum line length - recommended for a PyAnsys libary is 100. + recommended for a PyAnsys library is 100. - ``statistics`` This enables the number of occurrences of each error or warning code @@ -104,7 +104,7 @@ base. Utilizing Black ~~~~~~~~~~~~~~~ Manually checking for code styling can be a tedious task. Luckily, -several Python tools for autoformatting code to meet PEP8 standards +several Python tools for auto-formatting code to meet PEP8 standards are available to help with this. The PyAnsys project suggests the use of the the formatting tool `black`_. @@ -120,7 +120,7 @@ done with the tool `pre-commit`_. Setting up a `pre-commit hook to run black `_ will automatically format the code before committing. This simple way of incorporating code style checks into the development workflow to maintain -PEP8 guidelines requires mininmal manual effort. +PEP8 guidelines requires minimal manual effort. .. _pre-commit: https://pre-commit.com/ diff --git a/doc/source/coding_style/index.rst b/doc/source/coding_style/index.rst index d2ec3e0af..f9a3e7896 100644 --- a/doc/source/coding_style/index.rst +++ b/doc/source/coding_style/index.rst @@ -13,12 +13,12 @@ data science libraries: `NumPy`_, `SciPy`_, and `pandas`_. .. _PEP8: https://www.python.org/dev/peps/pep-0008/ -TODO: +.. todo:: -* Describe flake8 standards (in subpage), include example ``.flake8`` - with minimum standards. -* Include anythin we've written from other documentation either in - this page or other pages. + * Describe flake8 standards (in subpage), include example ``.flake8`` + with minimum standards. + * Include anything we've written from other documentation either in + this page or other pages. .. toctree:: :hidden: diff --git a/doc/source/conf.py b/doc/source/conf.py index e1ea8fd50..60dc75351 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -16,6 +16,7 @@ # Sphinx extensions extensions = [ + 'sphinx.ext.todo', 'sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.autosummary', diff --git a/doc/source/documentation_style/index.rst b/doc/source/documentation_style/index.rst index a0544012d..e275b380e 100644 --- a/doc/source/documentation_style/index.rst +++ b/doc/source/documentation_style/index.rst @@ -5,7 +5,7 @@ Documentation Style Good documentation drives library adoption and usage and is the foundation for a good developer experience. Even with the best interfaces and the most functional product, no one will adopt the API -if they don't know how to use it or if they aren't satisifed with the +if they don't know how to use it or if they aren't satisfied with the documentation or examples they are presented with. Good API documentation provides: diff --git a/doc/source/library_description/index.rst b/doc/source/library_description/index.rst index 9bf3e4539..c658b4a4b 100644 --- a/doc/source/library_description/index.rst +++ b/doc/source/library_description/index.rst @@ -47,7 +47,7 @@ The template repository contains a generalized library skeleton that includes: - 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 +- Licensing, example README, and setup files - ``.gitignore`` and other requirements files To use this template, `create a repository from a template`_. diff --git a/doc/source/library_description/library_names.rst b/doc/source/library_description/library_names.rst index 02e9ab5d2..819a1fa96 100644 --- a/doc/source/library_description/library_names.rst +++ b/doc/source/library_description/library_names.rst @@ -9,7 +9,7 @@ these naming conventions: is the project name for AEDT. - The repository name as hosted on GitHub should be all lowercase to follow GitHub community standards. For - exmaple, `pymapdl`_ and `pyaedt`_. + example, `pymapdl`_ and `pyaedt`_. - The Python library name is to be in the format ``ansys--``. For example, `ansys-mapdl-core `_ diff --git a/doc/source/library_description/packaging.rst b/doc/source/library_description/packaging.rst index 67ae4b343..08d633d2b 100644 --- a/doc/source/library_description/packaging.rst +++ b/doc/source/library_description/packaging.rst @@ -129,7 +129,7 @@ Install a package with: pip install ansys.. -To create a package complying with the above standards, here is the minimal content of your PyAnsys libary: +To create a package complying with the above standards, here is the minimal content of your PyAnsys library: .. code:: diff --git a/doc/source/overview/administration.rst b/doc/source/overview/administration.rst index 9599bacd8..421e766a6 100644 --- a/doc/source/overview/administration.rst +++ b/doc/source/overview/administration.rst @@ -86,9 +86,9 @@ Major releases denote global, major breaking API changes. Adding or changing a feature is not considered a globally-backwards incompatible API change. Rather, a major release and version bump should be made if globally-breaking changes are made that will require a -signifiant refactor of any dependent modules. +significant refactor of any dependent modules. -Note that ``0.MINOR.PATCH`` packges are expected to have fluid +Note that ``0.MINOR.PATCH`` packages are expected to have fluid APIs and should be solidified at the ``1.MINOR.PATCH`` release. At that point, APIs are expected to be much more stable. diff --git a/doc/source/overview/basic.rst b/doc/source/overview/basic.rst new file mode 100644 index 000000000..d08b63548 --- /dev/null +++ b/doc/source/overview/basic.rst @@ -0,0 +1,58 @@ +Quick Start Guide +================= + +This is a brief overview on how to get started right away with your own PyAnsys library on the `PyAnsys GitHub Organization`_ + +#. **Create the Repository:** Create a new repository from the + `pyansys/template`_. See + `Creating a repository from a template`_. Be sure to start as a + private repository. + +#. **Rename the Package:** Rename ``ansys/product/library`` to match + your product or library. For example ``ansys/mapdl/core``. Do the + same in ``setup.py``. Do this as a pull request. In fact, only add + code as pull requests (don't push to main). + +#. **Add Source:** Add your source files to + ``ansys//``, or create them. At the same time, + add unit tests to ``tests/`` following the `pytest`_ convention. + Be sure to maintain sufficient coverage when adding your library. + See `pytest-cov`_. + + .. note:: + If your tests require an active service, + application, or product, be sure to setup this application to run + in an automated manner. + +#. **Documentation:** Update documentation at ``doc/``. There are two + types of docs, User-Guide and API. Be sure that both are updated. + See :ref:`api_documentation`. + +#. **Package Release:** When ready to release your package publicly, + contact alexander.kaszynski@ansys.com to obtain the release + checklist in regards to official Ansys approval. Once the + checklist is complete, change the `repository visibility`_, + create a release branch. + +The manner of the source and content of the documentation will vary +from project to project. + +.. todo:: + + gRPC - Starting Guide + +.. todo:: + + C Extension - Starting Guide + +.. todo:: + + Others like requests, RPC, COM, etc. + + +.. _pytest-cov: https://pytest-cov.readthedocs.io/en/latest/reporting.html +.. _pyansys/template: https://github.com/pyansys/template +.. _Creating a repository from a template: https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template +.. _repository visibility: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/managing-repository-settings/setting-repository-visibility +.. _PyAnsys GitHub Organization: https://github.com/pyansys +.. _pytest: https://pytest.org/ diff --git a/doc/source/overview/contributing.rst b/doc/source/overview/contributing.rst index 65e1af1e8..dbbca27cc 100644 --- a/doc/source/overview/contributing.rst +++ b/doc/source/overview/contributing.rst @@ -7,9 +7,9 @@ contributing to a PyAnsys library. We welcome all code contributions and hope that this developer's guide facilitates an understanding of the PyAnsys code repository. It is important to -note that while Ansys maintains all PyAnsys libaries and thoroughly reviews all +note that while Ansys maintains all PyAnsys libraries and thoroughly reviews all submissions before merging, our goal is to foster a community that can support -user questions and develop new features to make PyAnsys libaries powerful tools +user questions and develop new features to make PyAnsys libraries powerful tools for all users. As such, we welcome and encourage the submittal of questions and code to this repository and all PyAnsys library repositories. @@ -52,7 +52,7 @@ screenshot, and sample files to help us address the issue. Issues ------ -For general or technical questions about a PyAnsys libary, its applications, or +For general or technical questions about a PyAnsys library, its applications, or about software usage, you can create issues for the applicable repository at: - `PyAEDT Issues `_ @@ -95,7 +95,7 @@ For example: pip install -e . Consider creating a fork of the repository if you want to eventually -push a contribution to the offical PyAnsys repository. +push a contribution to the official PyAnsys repository. .. https://docs.github.com/en/get-started/quickstart/fork-a-repo diff --git a/doc/source/overview/dev_practices.rst b/doc/source/overview/dev_practices.rst index 039c1a175..d6eb658dc 100644 --- a/doc/source/overview/dev_practices.rst +++ b/doc/source/overview/dev_practices.rst @@ -52,7 +52,7 @@ Consider the following general coding paradigms when contributing: guidelines, and always provide an example of simple use cases for new features. -3. **Test it**. Because Python is an interperted language, if it's not +3. **Test it**. Because Python is an interpreted language, if it's not tested, it's probably broken. At the minimum, include unit tests for each new feature within the ``tests`` directory. Ensure that each new method, class, or function has reasonable (>80%) coverage. @@ -143,7 +143,7 @@ Procedures follow for major and minor releases. production. Any bugs identified should have their hotfixes pushed to this release branch. -#. When the branch is deemed as stable for public release, the PR ismerged +#. When the branch is deemed as stable for public release, the PR is merged to `main` branch, which is then tagged with a `MAJOR.MINOR.0` release. The release branch will not be deleted. diff --git a/doc/source/overview/index.rst b/doc/source/overview/index.rst index a2c15d1f7..c929c746d 100644 --- a/doc/source/overview/index.rst +++ b/doc/source/overview/index.rst @@ -63,6 +63,7 @@ PROTO files, create coverage reports, and report on system coverage: :hidden: :maxdepth: 3 + basic administration contributing dev_practices