From 806f9d18134356e4b4d218f38bae9e85bf1da23b Mon Sep 17 00:00:00 2001
From: David Hendriks <davidhendriks93@gmail.com>
Date: Mon, 4 Jan 2021 19:02:31 +0000
Subject: [PATCH] updated the docs of the grid options and the stellar types
---
binarycpython/utils/grid_options_defaults.py | 39 +++++++++++++++-----
binarycpython/utils/stellar_types.py | 4 +-
2 files changed, 32 insertions(+), 11 deletions(-)
diff --git a/binarycpython/utils/grid_options_defaults.py b/binarycpython/utils/grid_options_defaults.py
index 90df8297e..3759ca669 100644
--- a/binarycpython/utils/grid_options_defaults.py
+++ b/binarycpython/utils/grid_options_defaults.py
@@ -1,9 +1,12 @@
"""
-Module that contains the default options for the population grid code,
+Module that contains the default options for the population grid code along with the description for these options, in the form of dictionaries:
+ - grid_options_defaults_dict: dictionary containing the default values for all the options
+ - grid_options_descriptions: dictionary containing the description for these options.
-along with a dictionary containing descriptions for each of the parameters, and some utility functions:
-- grid_options_help: interactive function for the user to get descriptions for options
-- grid_options_description_checker: function that checks that checks which options have a description.
+There are several other functions in this module, mostly to generate help texts or documents:
+ - grid_options_help: interactive function for the user to get descriptions for options
+ - grid_options_description_checker: function that checks that checks which options have a description.
+ - write_grid_options_to_rst_file: function to generate the .rst document for the docs
With this its also possible to automatically generate a pdf file containing all the setting names + descriptions.
@@ -472,9 +475,13 @@ grid_options_descriptions = {
# Grid options functions
# Utility functions
-def grid_options_help(option):
+def grid_options_help(option: str) -> str:
"""
- Function that returns the description of a grid option
+ Function that prints out the description of a grid option. Useful function for the user.
+
+ Args:
+ option: which option you want to have the description of
+
"""
option_keys = grid_options_defaults_dict.keys()
@@ -489,14 +496,22 @@ def grid_options_help(option):
else:
print(grid_options_descriptions[option])
-def grid_options_description_checker(print_info=True):
+def grid_options_description_checker(print_info: bool=True) -> int:
"""
- Function that checks which descriptions are missing
+ Function that checks which descriptions are missing
+
+ Args:
+ print_info: whether to print out information about which options contain proper descriptions and which do not
+
+ Returns:
+ the amount of undescribed keys
"""
+ # Get the keys
option_keys = grid_options_defaults_dict.keys()
description_keys = grid_options_descriptions.keys()
+ #
undescribed_keys = list(set(option_keys)-set(description_keys))
if undescribed_keys:
@@ -505,11 +520,15 @@ def grid_options_description_checker(print_info=True):
print("Total description progress: {:.2f}%%".format(100 * len(description_keys)/len(option_keys)))
return len(undescribed_keys)
-def write_grid_options_to_rst_file(output_file):
+def write_grid_options_to_rst_file(output_file: str) -> None:
"""
Function that writes the descriptions of the grid options to a rst file
- TODO: seperate things into private and public options
+ Tasks:
+ TODO: seperate things into private and public options
+
+ Args:
+ output_file: target file where the grid options descriptions are written to
"""
# Get the options and the description
diff --git a/binarycpython/utils/stellar_types.py b/binarycpython/utils/stellar_types.py
index d7b2e3b78..1043742e9 100644
--- a/binarycpython/utils/stellar_types.py
+++ b/binarycpython/utils/stellar_types.py
@@ -1,5 +1,7 @@
"""
-Module containing stellar type dicts
+Module containing two stellar type dicts:
+ - STELLAR_TYPE_DICT: dictionary with long names
+ - STELLAR_TYPE_DICT_SHORT: dictionary with short names/abbreviations
"""
STELLAR_TYPE_DICT = {
--
GitLab