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

Restructured development workflow and added code quality & documentation guidelines in it #1405

Merged
merged 62 commits into from
Jan 27, 2021

Conversation

KevinCawley
Copy link
Contributor

@KevinCawley KevinCawley commented Dec 30, 2020

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?

  • Testing pipeline
  • Other (please describe)

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

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • None of the above (please describe)

Checklist:

  • My code follows the code style of this project
  • My change requires a change to the documentation
  • I have updated the documentation accordingly
  • I have built the documentation on my fork following these instructions
  • I have assigned and requested two reviewers for this pull request

@jaladh-singhal
Copy link
Member

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):
image

How it will be after merging this PR:
image

@jaladh-singhal jaladh-singhal changed the title Creation of TARDIS Coding Guide, and instruction on building local docs. Restructured development workflow and added code quality & documentation guidelines in it Jan 21, 2021
Modified grammar, fixed a type, and made the docstring example comply with the guidelines stated below.
Adding the typo changes that I forgot to in the first commit
Added possessiveness
@andrewfullard andrewfullard merged commit a6d190c into tardis-sn:master Jan 27, 2021

.. code-block:: python

def read_density_file(filename, filetype):
"""
read different density file formats
Read different density file formats.
Copy link
Member

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.

Comment on lines 58 to 60
`filename` : str
filename or path of the density file
filetype : str
`filetype` : str
Copy link
Member

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!

@Molkree Molkree mentioned this pull request May 31, 2021
10 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Add Code quality guidelines to TARDIS docs Add documentation guidelines to TARDIS docs
3 participants