Merge pull request #111 from sadielbartholomew/minor-updates

Update and clarify aspects in documentation

cats/__init__.py

@@ -66,7 +66,7 @@ def parse_arguments():
     ********
 
     CATS can be used to report information on the best time to run a calculation
-    and the amount of CO2. Information about a 90 minute calculation in centeral
+    and the amount of CO2. Information about a 90 minute calculation in central
     Oxford can be found by running:
 
         cats -d 90 --loc OX1
@@ -81,8 +81,7 @@ def parse_arguments():
     To report carbon footprint, pass the `--config` option to select a
     configuration file and the `--profile` option to select a profile.
     The configuration file is documented in the Quickstart section of the online
-    documentation. An
-    example config file is given below:
+    documentation. An example config file is given below:
 
 .. code-block:: yaml
 
@@ -170,12 +169,12 @@ def positive_integer(string):
     parser.add_argument(
         "--cpu",
         type=positive_integer,
-        help="Number of cpus used by the job",
+        help="Number of CPUs used by the job",
     )
     parser.add_argument(
         "--gpu",
         type=positive_integer,
-        help="Number of cpus used by the job",
+        help="Number of GPUs used by the job",
     )
     parser.add_argument(
         "--memory",

docs/source/quickstart.rst

@@ -45,18 +45,29 @@ Use the ``--config`` option to specify a path to the configuration
 file, relative to the current directory.
 
 In case of a missing location command line argument, ``cats`` looks
-for a file named ``config.yaml`` in the current directory.
+for a file named ``config.yaml`` or ``config.yml`` in the current directory.
 
 .. code-block:: shell
 
    #  Override duration value at the command line
-   cats --config /path/to/config.yaml --location "OX1"
+   cats --config /path/to/config.y(a)ml --location "OX1"
 
-.. code-block:: shell
+When ``--duration`` information is not provided via the option, and
+location information is not provided in the YAML configuration file
+specified or detected, CATS will try to estimate location from the
+machine IP address:
+
+.. code-block:: console
+
+   $ cats --duration 480
+   WARNING:root:config file not found
+   WARNING:root:Unspecified carbon intensity forecast service, using carbonintensity.org.uk
+   WARNING:root:location not provided. Estimating location from IP address: RG2.
+   Best job start time 2024-08-22 07:30:49.800951+01:00
+   Carbon intensity if job started now       = 117.95 gCO2eq/kWh
+   Carbon intensity at optimal time          = 60.93 gCO2eq/kWh
 
-   #  location information is assumed to be provided in
-   #  ./config.yaml.  If not, 'cats' errors out.
-   cats --duration 480
+   Use --format=json to get this in machine readable format
 
 
 Displaying carbon footprint estimates