Skip to content
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.

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

docs: reformat the documentation #396

Merged
merged 58 commits into from
Jun 26, 2024
Merged

docs: reformat the documentation #396

merged 58 commits into from
Jun 26, 2024

Conversation

Revathyvenugopal162
Copy link
Contributor

@Revathyvenugopal162 Revathyvenugopal162 commented Jun 7, 2024

fix #373 #404
This pull request enhances the documentation for the Ansys Sphinx theme with the following updates:

  • User Guide: Updated to include comprehensive information.
  • Examples: Added demonstrations of style changes for all applicable extensions.
  • Copyright: Ensured proper attribution for examples, particularly from Sphinx Design and Admonitions, which were directly downloaded.
    exa_2
    exam_3
    exam_4
    exam_5
    exam_6
    examples_1
    userguide

@github-actions github-actions bot added the maintenance Generic maintenance related label Jun 19, 2024
@github-actions github-actions bot added the dependencies Related with project dependencies label Jun 19, 2024

This page contains the shipped extensions that seamlessly integrate with this theme to enhance
documentation functionality.

Linkcode extension
Copy link
Member

@PipKat PipKat Jun 25, 2024

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Linkcode extension
The ``linkcode`` extension

I can't find any doc that refers to this by anything but the extension/package name. Occurrences of "Linkcode" should be changed to linkcode extension.

Comment on lines 9 to 11
To use the ``ansys-sphinx-theme`` linkcode extension, you need to add it to the Sphinx configuration:

#. Add the following line in the ``conf.py`` file:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To use the ``ansys-sphinx-theme`` linkcode extension, you need to add it to the Sphinx configuration:
#. Add the following line in the ``conf.py`` file:
To use the ``linkcode`` extension, you must add it to the ``extensions`` variable in your
project's Sphinx ``conf.py`` file:

You shouldn't have a procedure with only one step. You will need to fix the indentation of the code block.

@@ -197,8 +197,6 @@ def link_code(app: Sphinx, doctree: Node):
The `link_code_library` configuration option can be used to specify a custom library
for link resolution.

Notes
-----
Adapted from the original `linkcode` extension in Sphinx, see
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Adapted from the original `linkcode` extension in Sphinx, see
Adapted from the original ``linkcode`` extension in Sphinx. For more information, see

What is adapted? This sentence needs a sentence and it should have display text for the link (rather than the URL itself).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

changed this to

The ``linkcode`` extension in this version has been adapted from the original 
`Sphinx linkcode extension <https://github.com/sphinx-doc/sphinx/blob/main/sphinx/ext/linkcode.py>`_.
This adaptation involves modifying the original code and functionality from the Sphinx library.

Comment on lines 197 to 198
The `link_code_library` configuration option can be used to specify a custom library
for link resolution.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `link_code_library` configuration option can be used to specify a custom library
for link resolution.
You can use the ``link_code_library`` configuration option to specify a custom library
for link resolution.

I'd like to make some edits to the preceding lines but I can't do so in this PR. There are additional places where single backticks are used instead of double backticks. Single backticks render as italics in the doc (rather than as a code entity).

Copy link
Member

@PipKat PipKat left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Lots of suggestions for you.

@Revathyvenugopal162
Copy link
Contributor Author

Thank you for the detailed review, @PipKat. I have addressed all the comments, I hope you can open a documentation review at your convenience once this PR is merged as mentioned above.

@Revathyvenugopal162 Revathyvenugopal162 merged commit 6a2c349 into main Jun 26, 2024
27 checks passed
@Revathyvenugopal162 Revathyvenugopal162 deleted the docs/reformat branch June 26, 2024 11:47
@Revathyvenugopal162 Revathyvenugopal162 linked an issue Jul 2, 2024 that may be closed by this pull request
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
dependencies Related with project dependencies maintenance Generic maintenance related
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add examples for all reformatted extensions in theme Improve the documentation
5 participants