Skip to content

Fix minor doc issues #32

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jan 19, 2022
Merged

Fix minor doc issues #32

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
33985fc
Fix minor doc issues
PipKat Jan 18, 2022
d560534
Fix use of both interpreted text role prefix and reference suffix
PipKat Jan 18, 2022
06b9610
Fix branch_naming`and and :ref:`branching_model
PipKat Jan 18, 2022
0941b92
Tried yet another approach to get past line 40
PipKat Jan 18, 2022
92445cf
Additional doc edits
PipKat Jan 19, 2022
5e3454f
Update doc/source/guidelines/dev_practices.rst
PipKat Jan 19, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 44 additions & 39 deletions doc/source/guidelines/dev_practices.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,14 +3,14 @@
Development Practices
=====================
This page explains how PyAnsys development is conducted. When
contributing directly to PyAnsys libraries, use these general
contributing to a PyAnsys repository, use these general
coding paradigms:

#. Follow the `Zen of Python <https://www.python.org/dev/peps/pep-0020/>`__.
As silly as core Python developers are sometimes, there's much to be
gained by following the basic guidelines listed in PEP 20. As suggested
in these guidelines, focus on making your additions intuitive, novel,
and helpful for PyAnsys library users. When in doubt, use ``import this``.
and helpful for PyAnsys users. When in doubt, use ``import this``.
For Ansys code quality standards, see :ref:`coding_style`.

#. Document your contributions. Include a docstring for any added
Expand All @@ -31,13 +31,15 @@ coding paradigms:

Contributing Through GitHub
---------------------------
To submit new code to a PyAnsys Library:
To submit new code to a PyAnsys repository:

#. `Fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_
the respective library's GitHub repository and then clone
the forked repository to your computer.
the respective GitHub repository and then clone the forked repository
to your computer.

#. In your local repository, create a branch. See `Branching Model <#Branching Model>`__.
#. In your local repository, create a branch. See :ref:`branch_naming`.
Comprehensive information on our model for branching is availible in
`Branching Model <#Branching Model>`__.

#. Add your new feature and commit it locally. Be sure to commit
frequently as the ability to revert to past commits is often helpful,
Expand All @@ -54,15 +56,15 @@ Once you have tested your branch locally, create a PR and target your
merge to ``main``. This will automatically run CI testing and verify
that your changes will work across all supported platforms.

For code verification, someone from the development team for the PyAnsys library
will review your code to verify that it meets our standards. Once your code
is approved, if you have write permission, you may merge the PR branch. If you
don't have write permission, the reviewer or someone else with write permission
will merge and delete the PR branch.
For code verification, someone from the PyAnsys development team will review your
code to verify that it meets our standards. Once your code is approved, if you
have write permission, you may merge the PR branch. If you don't have write
permission, the reviewer or someone else with write permission will merge your
PR and then delete your PR branch.

If your PR branch is a ``fix/`` branch, do not delete it because it may be necessary to
merge your PR branch with the current release branch. See the next section for branch
naming conventions.
merge your PR branch with the current release branch. The next section explains our
branch naming conventions.

.. _branch_naming:

Expand Down Expand Up @@ -124,7 +126,8 @@ like this:

Documentation
-------------
Documentation for a PyAnsys library is generated from three sources:
The source and content for documentation varies from repository to repository. For a PyAnsys library,
documentation is generated from three sources:

- Docstrings from the library's classes, functions, and modules using
`sphinx.ext.autodoc <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_.
Expand Down Expand Up @@ -161,21 +164,21 @@ and will be compiled dynamically during the build process. Always ensure that
examples run properly locally because they will be verified through the CI performed
via GitHub Actions.

Documentation for the latest stable release of a PyAnsys libary is accessible
from its repository. You can access the latest development version of the
Documentation for the latest stable release of a PyAnsys library is accessible
from its repository. You can generally access the latest development version of the
documentation tracking the ``main`` branch by adding the prefix ``dev.`` to
the URL for the latest stable release. For example, the URL for the latest
stable release of the PyAEDT documentation is
`<https://dev.aedtdocs.pyansys.com/>`_, and the URL for the latest development
version of this documentation is `<https://dev.aedtdocs.pyansys.com/>`_. The
latest development version is kept up-to-date automatically via GitHub actions.
the URL for the latest stable release. For example, the URL for documentation of the
latest stable release of PyAEDT is `<https://aedtdocs.pyansys.com/>`_, and
the URL for the latest documentation for the development version of PyAEDT is
`<https://dev.aedtdocs.pyansys.com/>`_. The latest development versions of both
the library and its documentation are kept up-to-date automatically via GitHub actions.

Building the Documentation Locally
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can build and verify a library's HTML documentation locally by installing
Sphinx and other documentation build dependencies.
Building Documentation Locally
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can build and verify the HTML documentation for a PyAnsys project locally
by installing Sphinx and other documentation build dependencies.

#. Optionally install the library in development mode:
#. Optionally install the project in development mode:

.. code::

Expand All @@ -201,14 +204,14 @@ Otherwise, if running on Windows, build the documentation:
cd doc
make.bat html

#. After documentation builds successfully locally, use your
browser to open the file ``index.html`` in ``doc/_build/html/``
to review it.
#. After documentation builds successfully locally, navigate to
``doc/_build/html/`` and use your browser to open the
``index.html`` so that you can review the documenation.

Continuous Integration and Continuous Delivery (CI/CD)
------------------------------------------------------

A PyAnsys library uses continuous integration (CI) and continuous delivery (CD)
A PyAnsys project uses continuous integration (CI) and continuous delivery (CD)
to automate building, testing, and deployment tasks. The CI pipeline is
deployed on both GitHub Actions and Azure Pipelines and performs the following
tasks:
Expand All @@ -218,9 +221,11 @@ tasks:
- Spelling and style verification
- Documentation build

.. _branching_model:

Branching Model
---------------
The branching model for a PyAnsys library enables rapid development of
The branching model for a PyAnsys project enables rapid development of
features without sacrificing stability. The model closely follows the
`Trunk Based Development <https://trunkbaseddevelopment.com/>`_ approach:

Expand Down Expand Up @@ -276,11 +281,10 @@ Release procedures follow for major and minor releases.
#. After building the documentation, open the local build and examine
the examples for any obvious issues.

#. Update the version numbers in
``ansys/<product>/<library>/_version.py`` and commit this file. Push the
branch to GitHub and create a new PR for this release that merges
it to ``main``. While effort is focused on the release, development
to ``main`` should be limited.
#. Update the version numbers in ``ansys/<product>/<library>/_version.py``
and commit this file. Push the branch to GitHub and create a new PR
for this release that merges it to ``main``. While effort is focused
on the release, development to ``main`` should be limited.

#. Wait for the PyAnsys developers and community to functionally test the
new release. Testors should locally install this branch and use it in
Expand Down Expand Up @@ -327,11 +331,12 @@ should not wait until a minor release. These are the steps for a patch release:
an opportunity to validate and approve the bug fix release. Any
additional hotfixes should be outside of this PR.

#. When the PR is approved, merge it with the release branch, but not with
``main`` as there is no reason to increment the version of the ``main`` branch.
#. When the PR is approved, merge it with the release branch but not with
``main`` because there is no reason to increment the version of the
``main`` branch.

#. Create a tag from the release branch with the applicable version number
as described in the previous section.

4. If deemed necessary, create and add release notes as described in the
#. If deemed necessary, create and add release notes as described in the
previous section.
61 changes: 30 additions & 31 deletions doc/source/overview/basic.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,40 @@
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`_
This is a brief overview on how to get started right away with your own PyAnsys
repository on the `PyAnsys GitHub Organization`_. A repository is generally a
project for a particular PyAnsys library.

#. **Create the repository:** Create a repository from the
`pyansys/template`_. See `Creating a repository from a template`_.
Be sure that the `repository visibility`_ is initially private.

#. **Rename the package:** Rename ``ansys/product/library`` to match
your product or library. For example, the package name for
PyMAPDL is ``ansys/mapdl/core``. Do the
same renaming in ``setup.py``. Do this as a pull request. In fact, only add
code as pull requests. Do not push to ``main``.)

#. **Add source:** Add your source files to
``ansys/<product>/<library>`` or create them. Also add unit tests to
``tests/`` following the `pytest`_ convention. Be sure to maintain
sufficient coverage when adding your library. See `pytest-cov`_.

#. **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.
.. note::
If your tests require an active service, application, or product,
be sure to set up this application to run in an automated manner.

#. **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).
#. **Update documentation:** The documentation source and content will
vary from repository to _repository. In ``doc/``, there are folders for
different types of documentation, which can include guides, examples,
and API. Ensure that all documentation is updated. See :ref:`api_documentation`.

#. **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`_.
#. **Prepare the package for release:** When you are ready to release
your package publicly, email `pyansys.support@ansys.com <pyansys.support@ansys.com>`_
to obtain the release checklist for obtaining official Ansys approval.
Once you have completed this checklist, change the `repository visibility`_
to public and create a release branch.

.. 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::

Expand Down
75 changes: 37 additions & 38 deletions doc/source/overview/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,13 @@ our libraries powerful tools for all users. As such, we
encourage you to submit questions, report bugs, request new
features, contribute code, and start discussions.

This page provides general information about contributing to a
PyAnsys library. Contribution information specific to a particular
library appears on the ``Contributing`` page in the respective
library's documentation, including:
This page provides general information about contributing code to a
PyAnsys respository. Contribution information specific to a particular
repository appears on the ``Contributing`` page in the respective
respository's documentation, including:

- Instructions for cloning the source repository from GitHub
- URL to the library's ``Issues`` page
- URL to the repository's ``Issues`` page

Creating Issues
---------------
Expand All @@ -36,8 +36,9 @@ it with a comment that explains why you have done so. If you need to contact the
PyAnsys project support team directly, email `pyansys.support@ansys.com <pyansys.support@ansys.com>`_.

For convenience, here are URLs for ``Issues`` pages for
Ansys product repositories:
public Ansys repositories:

- `OpenAPI Common Issues <https://github.com/pyansys/openapi-common/issues>`_
- `PyAEDT Issues <https://github.com/pyansys/pyaedt/issues>`_
- `PyDPF-Core Issues <https://github.com/pyansys/pydpf-core/issues>`_
- `PyDPF-Post Issues <https://github.com/pyansys/pydpf-post/issues>`_
Expand All @@ -46,61 +47,59 @@ Ansys product repositories:

Submitting Questions
~~~~~~~~~~~~~~~~~~~~
For general or technical questions about a PyAnsys library, its
applications, or software usage, create issues on the respective
library's ``Issues`` page. This allows PyAnsys developers and
community members with the needed expertise to collectively address
them. It also makes their responses available to all users.
For general or technical questions about the code in a PyAnsys repository or
about its application or software usage, create issues on the ``Issues`` page
of the repository. This allows PyAnsys developers and community members with
the needed expertise to collectively address them. It also makes their responses
available to all users.

Reporting Bugs
~~~~~~~~~~~~~~
If you encounter a bug or your workflow crashes while using a
PyAnsys library, create an issue on the respective library's
``Issues`` page and tag it with an appropriate label so that it
can be promptly addressed. In describing the issue, be as descriptive
as possible so that the issue can be reproduced. Whenever possible,
provide a traceback, screenshots, and sample files that might help
the community to address the issue.
If you encounter a bug or your workflow crashes while using code in a PyAnsys
repository, create an issue on the repository's ``Issues`` page and tag it with
an appropriate label so that it can be promptly addressed. In describing the
issue, be as descriptive as possible so that the issue can be reproduced.
Whenever possible, provide a traceback, screenshots, and sample files that might
help the community to address the issue.

Requesting New Features
~~~~~~~~~~~~~~~~~~~~~~~
We encourage you to submit ideas for improving PyAnsys libraries.
To suggest a new feature, create an issue on the respective library's
``Issues`` page and tag it with the ``Feature Request`` label. Use a
descriptive title and provide ample background information to help the
community decide how the feature might be implemented. For example,
if you would like to see a reader added for a specific file format,
in the issue, provide a link to documentation for this file
format and possibly some sample files and screenshots. The community
will then use the issue thread to discuss the request and
provide feedback on how the feature might best be implemented.
We encourage you to submit ideas for improving the code in a PyAnsys
repository. To suggest a new feature, create an issue on the repository's
``Issues`` page and tag this issue with the ``Feature Request`` label.
Use a descriptive title and provide ample background information to help the
community decide how the feature might be implemented. For example, if you
would like to see a reader added for a specific file format, in the issue,
provide a link to documentation for this file format and possibly some sample
files and screenshots. The community will then use the issue thread to discuss
the request and provide feedback on how the feature might best be implemented.

Contributing New Code
---------------------
When you are ready to start contributing code, see:

- :ref:`development_practices` for information on how development is
conducted in PyAnsys repositories
- :ref:`development_practices` for information on how PyAnsys development is
conducted
- :ref:`best_practices` for information on how to style and format your
code to adhere to PyAnsys standards

Starting Discussions
--------------------
For general questions about development practices, you should create discussions
rather than issues. The repository for each PyAnsys library has its own
``Discussions`` page. For example, to ask a question about a PyMAPDL development
practice, you would create a discussion on this library's `Discussions <https://github.com/pyansys/pymapdl/discussions>`_
rather than issues. Each PyAnsys repository has its own ``Discussions`` page.
For example, to ask a question about a PyMAPDL development practice, you would
create a discussion on the `PyMAPDL Discussions <https://github.com/pyansys/pymapdl/discussions>`_
page. It is possible for discussions to lead to the creation of issues.

.. note::
Because the ``Discussions`` page is still a beta feature on GitHub, usage
Because the ``Discussions`` page is still a GitHub beta feature, usage
may change in the future.

Cloning the Source Repository
-----------------------------
As mentioned earlier, specific instructions for cloning a source
repository from GitHub appear on the ``Contributing`` page in the
respective library's documentation. In the following code for cloning and
respective repository's documentation. In the following code for cloning and
installing the latest version of a PyAnsys repository, ``<pyansy-repository>``
is a placeholder for the name of the repository.

Expand All @@ -119,7 +118,7 @@ you would run the following:
cd pymapdl
pip install -e .

If you want to eventually push a contribution to the official
If you want to eventually push a contribution to a
PyAnsys repository, consider creating a `fork <https://docs.github.com/en/get-started/quickstart/fork-a-repo>`_
of the repository. For information on how to contribute through
GitHub, see :ref:`development_practices`, paying particular attention to :ref:`branch_naming`
Expand All @@ -128,8 +127,8 @@ when you are ready to create a pull request.
Licensing
---------
All contributed code will be licensed under the MIT License. For more information, see
:ref:`license_file`. The ``LICENSE`` file with the MIT License must be included in
the root directory of the repository for a PyAnsys library.
:ref:`license_file`. The ``LICENSE`` file containing the MIT License must be included in
the root directory of a PyAnsys repository.

If you did not write the code that you are contributing yourself, it is your
responsibility to ensure that the existing license for this code is compatible and
Expand Down