Skip to content

include vale for documentation enhancement #23

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

Merged
merged 3 commits into from
Jun 21, 2022
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
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
20 changes: 20 additions & 0 deletions .github/workflows/ci_cd.yml
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,24 @@ jobs:
- name: Test with tox
run: tox -e style

docs-style:
name: Documentation Style Check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3

- name: Running Vale
uses: errata-ai/vale-action@reviewdog
env:
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
with:
files: doc
reporter: github-pr-check
level: error
filter_mode: nofilter
fail_on_error: true
vale_flags: "--config=doc/.vale.ini"

tests:
name: Build and testing
runs-on: ubuntu-latest
Expand Down Expand Up @@ -89,6 +107,8 @@ jobs:
docs:
name: Documentation
runs-on: ubuntu-latest
needs: [docs-style]

steps:
- uses: actions/checkout@v3

Expand Down
14 changes: 7 additions & 7 deletions README.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
PyOptics Library
PyOptics library
================
|pyansys| |GH-CI| |MIT| |black|

Expand All @@ -18,7 +18,7 @@ PyOptics Library
:alt: Black


Project Overview
Project overview
----------------
``PyOptics`` is a Python library that gathers functionalities and tools based on remote API of Ansys software `Speos <https://www.ansys.com/fr-fr/products/optics-vr>`_, `Zemax <https://www.zemax.com/>`_ and `Lumerical <https://www.lumerical.com/>`_.

Expand All @@ -28,7 +28,7 @@ Installation can be done using the published `package`_ or the repository `sourc

Package
~~~~~~~
.. warning:: Not currently available, work in progress... Please use `Sources`_.
.. warning:: Not currently available, work in progress. Please use `Sources`_.

This repository is deployed as the Python packages `ansys-pyoptics <...>`_.
As usual, installation is done by running:
Expand All @@ -39,8 +39,8 @@ As usual, installation is done by running:

Sources
~~~~~~~
**Prerequisite**: User needs to have a GitHub account and a valid Personnal Access Token
(see GitHub Settings/Developer settings/Personnal access tokens/Generate new token).
**Prerequisite**: user needs to have a GitHub account and a valid Personal Access Token
(see GitHub Settings/Developer settings/Personal access tokens/Generate new token).

Clone and install
^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -77,7 +77,7 @@ To build it manually, just run:

.. note::

Include a link to the full sphinx documentation. For example `PyAnsys <https://docs.pyansys.com/>`_
Include a link to the full sphinx documentation. For example `PyAnsys <https://docs.pyansys.com/>`_

Testing
-------
Expand All @@ -89,7 +89,7 @@ Test configuration file
~~~~~~~~~~~~~~~~~~~~~~~
The configuration file `<tests/local_config.json>`_ located in tests folder contains several parameters that can be changed according to your needs, for example:

- **SpeosServerOnDocker** (boolean): Speos server launched in a docker container.
- **SpeosServerOnDocker** (Boolean): Speos server launched in a docker container.
- **SpeosServerPort** (integer): Port used by Speos server for HTTP transfer.

Start server
Expand Down
28 changes: 28 additions & 0 deletions doc/.vale.ini
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
# Core settings
# =============

# Location of our `styles`
StylesPath = "styles"

# The options are `suggestion`, `warning`, or `error` (defaults to “warning”).
MinAlertLevel = warning

# By default, `code` and `tt` are ignored.
IgnoredScopes = code, tt

# By default, `script`, `style`, `pre`, and `figure` are ignored.
SkippedScopes = script, style, pre, figure

# WordTemplate specifies what Vale will consider to be an individual word.
WordTemplate = \b(?:%s)\b

# List of Packages to be used for our guidelines
Packages = Google

# Define the Ansys vocabulary
Vocab = ANSYS

[*.{md,rst}]

# Apply the following styles
BasedOnStyles = Vale, Google
2 changes: 1 addition & 1 deletion doc/source/_static/README.md
Original file line number Diff line number Diff line change
@@ -1 +1 @@
Static files will be found here (like images and other assets).
Static files can found here(like images and other assets).
6 changes: 3 additions & 3 deletions doc/source/class_documentation.rst
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
***************************
Generate APIs Documentation
Generate APIs documentation
***************************

Autosummary Directive
Autosummary directive
~~~~~~~~~~~~~~~~~~~~~
We use a custom class template (included in ``_template``) to
This project use a custom class template (included in ``_template``) to
automatically generate class and method documentation.

.. autosummary::
Expand Down
4 changes: 2 additions & 2 deletions doc/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,14 +13,14 @@
class_documentation


Code Examples
Code examples
~~~~~~~~~~~~~
Here's a quick preview for how Python code looks using the
``ansys-pyoptics``. For more examples, click the links at the
top of the page to see function, method, and class documentation.


Rendered Python Code
Rendered python code
--------------------

.. code:: python
Expand Down
4 changes: 4 additions & 0 deletions doc/styles/.gitignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
*
!Vocab
!Vocab/**
!.gitignore
13 changes: 13 additions & 0 deletions doc/styles/vocab/ANSYS/accept.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
ANSYS
Ansys
ansys
Pyoptics
PyOptics
pyoptics
API

Speos
Lumerical
Zemax
Autosummary
autosummary
Empty file.