-
-
Notifications
You must be signed in to change notification settings - Fork 409
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
Restructured development workflow and added code quality & documentation guidelines in it #1405
Conversation
…hose files no longer exist
Co-authored-by: Jaladh Singhal <[email protected]>
Other than editing documentation and code quality guidelines, I've restructured developer workflow to make it more sensible. How it used to be (https://tardis-sn.github.io/tardis/development/index.html): |
Modified grammar, fixed a type, and made the docstring example comply with the guidelines stated below.
Editted the grammar
Adding the typo changes that I forgot to in the first commit
Added possessiveness
|
||
.. code-block:: python | ||
|
||
def read_density_file(filename, filetype): | ||
""" | ||
read different density file formats | ||
Read different density file formats. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please also make the same change in respective file.
docs/development/code_quality.rst
Outdated
`filename` : str | ||
filename or path of the density file | ||
filetype : str | ||
`filetype` : str |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why? backticks are not required for parameter, return names - please undo this!
This PR creates the Coding and Docstring Guidelines for TARDIS, as well as how to create docs locally. It also addressed some of the syntax errors that occurred when docs were compiled locally.
Description
The first file that is added is Code_Quality_Guidelines.rst. This file addresses the code standard of TARDIS. The main section is the use of Black to format code files to create consistency in the code that is submitted.
The next section of this file addresses the handling of exception and raising errors. This is made so that invalid input can be dealt with and the user can be alerted to their error, and the code should be written so that edge cases are caught so unknown and strange errors are avoided.
The third section deals with Docstrings. This section creates the guideline for how docstrings should be formatted, and gives clear directions as to the required syntax for docstrings, with a lot of influence from numpydocs.
The final section is a brief section about the naming conventions used in TARDIS, and heavily draws from the PEP8 naming convention.
The next change is in git_workflow.rst. This section gives directions for how to build and compile docs locally, and the importance and benefits of compiling docs locally before being submitted in a commit or merge. This is an alternative way to look at the TARDIS docs, and a faster method than the this one ( https://tardis-sn.github.io/tardis/development/documentation_preview.html). Both methods accomplish the same task, there is no difference in the docs created.
The remaining changes are to the index.rst file to include my Code_Quality_Guidelines.rst file. Another changes is the removal of a branch of the index.rst in tardis/docs that is outdated (and does not compile as the files no longer exist). All of the other changes are changes to resolve syntax errors that occur when docs are compiled locally, most of them involving the lack of a newline when the documentation syntax expects there to be one.
Motivation and Context
This was done to address three Issues (1170, 1252, and 1253). This will create a consistent method and guideline for how to code in TARDIS and how to write docstrings. This will reduce time made changing commits in the future to adhere to the guideline, as it will be written out and a lot easier to follow.
Partially covers: #1170 (enforcing by pre-commit hook will be in another PR)
Fixes #1252
Fixes #1253
How Has This Been Tested?
The changes were tested by compiling docs locally, and also online when my version of TARDIS was broken due to untracked files. This also allowed both methods (online and local) to be tested.
Screenshots (if appropriate):
Types of changes
Checklist: