From 30503b5a1578de4bd2958932c47666f911458d87 Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Mon, 21 Feb 2022 15:29:37 +0100 Subject: [PATCH 1/5] Add Documentation page DNS. --- doc/source/guidelines/doc_practices.rst | 39 ++++++++++++++++++++----- 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index fde78c79b..1a654b313 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -8,8 +8,8 @@ Guide `_. It provides editorial gu for writing clear and consistent developer documentation, allowing this guide to supply guidance specific to PyAnsys library documentation. -When writing developer documentation, the relationship between code and documenation is -key. To keep documentation up to date with rapdily evolving code: +When writing developer documentation, the relationship between code and documentation is +key. To keep documentation up to date with rapidly evolving code: - Minimize the content footprint - Write `timeless documentation `_ @@ -122,6 +122,31 @@ extension, you must follow its `coding guidelines `_. + +Documentation page DNS +---------------------- +To host the documentation related to a PyAnsys project, an easy way to go is to use GitHub Page. +This GitHub feature do not require any database to be setup nor to configure any server. +GitHub will serve the documentation of related to the project from a URL tied to PyAnsys organization. + +The standard name for this URL can be such as: + .docs.pyansys.com + +For instance: +`grantami.docs.pyansys.com `_ + +Regarding documentation dedicated to a specific feature of the product or an example, the URL can be such as: + ..docs.pyansys.com + +For instance: +`cartpole.mapdl.docs.pyansys.com `_ + +Once the URL name has been decided, it must be specified in the "Settings" of the repository under the "Custom domain" section. +*For example, see https://github.com/pyansys/grantami-bomanalytics-docs/settings/pages* + +Then, the URL must be registered using Microsoft Azure to set the DNS properly and link it to the ANSYS organization. +This action will be performed by one of the Ansys administrator of Microsoft Azure account. + Accessing a Library's Documentation ----------------------------------- Documentation for the latest stable release of a PyAnsys library is accessible @@ -166,7 +191,7 @@ To use Windows PowerShell to clone a GitHub repository: Because the list of repositories is quite long, you can use the ``Find a repository`` option to search for the repository that you want to clone. For - example, you can seach for "theme" to find the ``pyansys-sphinx-theme`` repository. + example, you can search for "theme" to find the ``pyansys-sphinx-theme`` repository. #. In the upper right corner of the repository, click the green ``Code`` button to drop down a list of options. @@ -206,7 +231,7 @@ Pushing Changes to the GitHub Repository ---------------------------------------- As you make changes in your ``doc/`` branch, you want to periodically test then in local documentation builds as described in :ref:`doc_building`. After you resolve -any issues and are satisfied with what apears in a local build, you are ready +any issues and are satisfied with what appears in a local build, you are ready to push your changes to the library's GitHub repository. To accomplish this, you can use either Git commands or Git Extensions. @@ -290,7 +315,7 @@ To use Git Extensions to push your changes to the GitHub repository: are no conflicts with what is in your branch. If there are conflicts, resolve them. -#. Do a push of your branch to the GitHub repsitory. +#. Do a push of your branch to the GitHub repository. #. Create the PR as described in :ref:`create_pr`. @@ -302,7 +327,7 @@ Creating the GitHub PR Regardless of what method you used to push your changes, do the following to create the GitHub PR: -#. Go to the GitHub reposity, where you will see an entry for your pushed branch. +#. Go to the GitHub repository, where you will see an entry for your pushed branch. #. If the pushed branch resolves an issue, in its description, type ``Resolves #`` and select from the list of issues that appears. @@ -313,7 +338,7 @@ the GitHub PR: If your PR is ready for review, select ``Create pull request``. Otherwise, select ``Create draft pull request`` and mark it as ready for review once - you it includes all of your changes and you are satisified with it. + you it includes all of your changes and you are satisfied with it. If you need to change a PR title, to its right, click the ``Edit`` button, which becomes a ``Save`` button while you are in editing mode. From 2c8280d33a53284166ca5f6c60bf87363fea395e Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Mon, 21 Feb 2022 16:03:36 +0100 Subject: [PATCH 2/5] Small improvement. --- doc/source/guidelines/doc_practices.rst | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index 1a654b313..35aa4ec13 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -123,28 +123,28 @@ extension, you must follow its `coding guidelines `_. -Documentation page DNS ----------------------- +URL of the documentation page +----------------------------- To host the documentation related to a PyAnsys project, an easy way to go is to use GitHub Page. This GitHub feature do not require any database to be setup nor to configure any server. -GitHub will serve the documentation of related to the project from a URL tied to PyAnsys organization. +GitHub will serve the documentation related to the project from a URL tied to PyAnsys organization. The standard name for this URL can be such as: - .docs.pyansys.com + ``.docs.pyansys.com`` For instance: `grantami.docs.pyansys.com `_ -Regarding documentation dedicated to a specific feature of the product or an example, the URL can be such as: - ..docs.pyansys.com +Regarding the documentation dedicated to a specific feature of the product or an example, the URL can be such as: + ``..docs.pyansys.com`` For instance: `cartpole.mapdl.docs.pyansys.com `_ Once the URL name has been decided, it must be specified in the "Settings" of the repository under the "Custom domain" section. -*For example, see https://github.com/pyansys/grantami-bomanalytics-docs/settings/pages* +For example, `see https://github.com/pyansys/grantami-bomanalytics-docs/settings/pages`__ -Then, the URL must be registered using Microsoft Azure to set the DNS properly and link it to the ANSYS organization. +Then, the URL has to be registered using Microsoft Azure to set the DNS properly and link it to the ANSYS organization. This action will be performed by one of the Ansys administrator of Microsoft Azure account. Accessing a Library's Documentation From 1905c3e2d87c3a5cc2edd9a85e22558b56c306ef Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Mon, 21 Feb 2022 16:13:13 +0100 Subject: [PATCH 3/5] Correct hyperlink. --- doc/source/guidelines/doc_practices.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index 35aa4ec13..02019a571 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -132,17 +132,15 @@ GitHub will serve the documentation related to the project from a URL tied to Py The standard name for this URL can be such as: ``.docs.pyansys.com`` -For instance: -`grantami.docs.pyansys.com `_ +For instance: `grantami `_ Regarding the documentation dedicated to a specific feature of the product or an example, the URL can be such as: ``..docs.pyansys.com`` -For instance: -`cartpole.mapdl.docs.pyansys.com `_ +For instance: `cartpole `_ Once the URL name has been decided, it must be specified in the "Settings" of the repository under the "Custom domain" section. -For example, `see https://github.com/pyansys/grantami-bomanalytics-docs/settings/pages`__ +For example, `see https://github.com/pyansys/grantami-bomanalytics-docs/settings/pages`_ Then, the URL has to be registered using Microsoft Azure to set the DNS properly and link it to the ANSYS organization. This action will be performed by one of the Ansys administrator of Microsoft Azure account. From cb291054b73c3f6bcfe86105a0e6b22cd60b231c Mon Sep 17 00:00:00 2001 From: Maxime Rey Date: Mon, 21 Feb 2022 16:16:31 +0100 Subject: [PATCH 4/5] Correct hyperlink for settings page. --- doc/source/guidelines/doc_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index 02019a571..50a9270da 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -140,7 +140,7 @@ Regarding the documentation dedicated to a specific feature of the product or an For instance: `cartpole `_ Once the URL name has been decided, it must be specified in the "Settings" of the repository under the "Custom domain" section. -For example, `see https://github.com/pyansys/grantami-bomanalytics-docs/settings/pages`_ +For example, `see `_ Then, the URL has to be registered using Microsoft Azure to set the DNS properly and link it to the ANSYS organization. This action will be performed by one of the Ansys administrator of Microsoft Azure account. From 1b5be610bd04c63c6fcff483d02eb30e8ecdfbff Mon Sep 17 00:00:00 2001 From: Maxime Rey <87315832+MaxJPRey@users.noreply.github.com> Date: Mon, 21 Feb 2022 16:32:10 +0100 Subject: [PATCH 5/5] Update doc/source/guidelines/doc_practices.rst Co-authored-by: Kathy Pippert <84872299+PipKat@users.noreply.github.com> --- doc/source/guidelines/doc_practices.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/guidelines/doc_practices.rst b/doc/source/guidelines/doc_practices.rst index 50a9270da..bd8f74fd6 100644 --- a/doc/source/guidelines/doc_practices.rst +++ b/doc/source/guidelines/doc_practices.rst @@ -134,7 +134,7 @@ The standard name for this URL can be such as: For instance: `grantami `_ -Regarding the documentation dedicated to a specific feature of the product or an example, the URL can be such as: +Regarding the documentation dedicated to a specific feature of the product or an example, the URL is formatted like this: ``..docs.pyansys.com`` For instance: `cartpole `_