add basic example workflow (#13)

akaszynski · web-flow · commit 0f002e5de226 · 2021-09-29T23:12:13.000-06:00
* add basic example workflow

* add basic starting guide

* spelling fixes

* libary --&gt; library
diff --git 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
@@ -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
@@ -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 <https://black.readthedocs.io/en/stable/integrations/source_version_control.html>`_
 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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-<product/service>-<feature>``. For example, 
   `ansys-mapdl-core <https://pypi.org/project/ansys-mapdl-core/>`_ 
diff --git 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.<product>.<library>
 
-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
@@ -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
@@ -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/<product>/<library>``, 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
@@ -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 <https://github.com/pyansys/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
@@ -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
@@ -63,6 +63,7 @@ PROTO files, create coverage reports, and report on system coverage:
    :hidden:
    :maxdepth: 3
 
+   basic
    administration
    contributing
    dev_practices
