Dev (#9)

.editorconfig

@@ -9,4 +9,12 @@ indent_size = 4
 end_of_line = lf
 charset = utf-8
 trim_trailing_whitespace = true
+insert_final_newline = false
+
+[{*,md}]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = false
 insert_final_newline = false

Finance/.nuspec

@@ -2,7 +2,7 @@
 <package  xmlns="http://schemas.microsoft.com/packaging/2013/05/nuspec.xsd">
     <metadata>
         <id>CosminSanda.Finance</id>
-        <version>1.0.2</version>
+        <version>1.1.0</version>
         <title>Yahoo Earnings Calendar</title>
         <authors>Cosmin Catalin Sanda</authors>
         <owners>cosmincatalin</owners>

Finance/EarningsCalendar.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.Linq;
 using System.Threading.Tasks;
 using CosminSanda.Finance.Records;
@@ -20,15 +21,25 @@ public static class EarningsCalendar
     /// using CosminSanda.Finance;
     ///
     /// var companies = await EarningsCalendar
-    ///     .GetCompaniesReporting(new DateTime(year: 2022, month: 9, day: 28));
+    ///     .GetCompaniesReporting("2022-09-28");
     /// companies.ForEach(Console.WriteLine);
     /// </code>
     /// </example>
-    /// <param name="day">The day for which you want to know the companies reporting earnings</param>
+    /// <param name="day">The date string (yyyy-MM-dd format) for which you want
+    /// to know the companies reporting earnings</param>
     /// <returns>A list of companies</returns>
-    public static async Task<List<FinancialInstrument>> GetCompaniesReporting(DateTime day)
+    public static async Task<List<FinancialInstrument>> GetCompaniesReporting(string day)
     {
-        var date = DateOnly.FromDateTime(day);
+        var date = DateOnly.FromDateTime(
+            DateTime
+                .ParseExact(
+                    day,
+                    "yyyy-MM-dd",
+                    CultureInfo.InvariantCulture,
+                    DateTimeStyles.AdjustToUniversal | DateTimeStyles.AssumeUniversal
+                )
+                .ToUniversalTime()
+        );
 
         var earnings = await Scraper.RetrieveEarningsReleases(date);
         return earnings.Select(o => o.FinancialInstrument).ToList();

Finance/Quotes.cs

@@ -19,8 +19,8 @@ public static class Quotes
     /// Retrieve the Japanese candles for each day of a time interval for a specified company.
     /// </summary>
     /// <param name="ticker">The financial instrument's ticker as used on Yahoo Finance.</param>
-    /// <param name="startDate">The day from when you start retrieving the quotes, inclusive.</param>
-    /// <param name="endDate">The day until when you retrieve the quotes, inclusive</param>
+    /// <param name="startDate">The day from when you start retrieving the quotes, inclusive (yyyy-MM-dd format).</param>
+    /// <param name="endDate">The day until when you retrieve the quotes, inclusive (yyyy-MM-dd format).</param>
     /// <returns>A list of quotes in ascending order</returns>
     public static async Task<List<Candle>> GetQuotes(
         string ticker,
@@ -106,7 +106,8 @@ string endDate
         var end = earningsDate.Date.AddDays(1);
         while (Util.IsHoliday(end))
             end = end.AddDays(1);
-        if (earningsDate.DateType == "BMO") {
+        if (earningsDate.DateType == "BMO")
+        {
             start = earningsDate.Date.AddDays(-1);
             while (Util.IsHoliday(start))
                 start = start.AddDays(-1);

docfx_project/api/index.md

@@ -1,2 +1,20 @@
-# PLACEHOLDER
-TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
+# Installation
+
+## dotnet-interactive
+
+In a `dotnet-interactive` notebook, the library can be installed with
+
+```csharp
+#r "nuget: CosminSanda.Finance"
+```
+
+Although transient dependencies should be installed as well, in the notebook context that does not seem to the case, so ou might also need to run:
+
+```csharp
+#r "nuget: CsvHelper"
+#r "nuget: ServiceStack.Text"
+```
+
+## .NET project
+
+The ubiquitous `Install-Package CosminSanda.Finance`.

docfx_project/docfx.json

@@ -25,8 +25,8 @@
             },
             {
                 "files": [
-                    "articles/**.md",
-                    "articles/**/toc.yml",
+                    "tutorials/**.md",
+                    "tutorials/**/toc.yml",
                     "toc.yml",
                     "*.md"
                 ]

docfx_project/index.md

@@ -2,20 +2,17 @@
 
 ## Description
 
-This package simplifies the process of retrieving data from Yahoo Finance.
-Currently, it can fetch information about earnings calls and about daily quotes.
+This package simplifies the process of retrieving data from Yahoo Finance.  
+Currently, it can fetch information about earnings calls and about daily quotes.  
 
 This package can be used, typically, to analyze the price action around historical earnings calls for the purpose
-of establishing strategies for future earnings releases a.k.a "Playing the Earnings".
+of establishing strategies for future earnings releases a.k.a "Playing the Earnings".  
 
-The package acts as a proxy to Yahoo Finance and is essentially a web scraper.
-While in previous versions, caching was built in, it has been removed.
-That means all methods make requests directly to Yahoo Finance and it is your responsibility to cache the data so as to avoid redundant requests.
-The reason for disabling the cache has to do with the lack of guarantees regarding the provided data which can lead to inconsistencies for less popular instruments.
+The package acts as a proxy to Yahoo Finance and is essentially a web scraper.  
+While in previous versions, caching was built in, it has been removed.  
+That means all methods make requests directly to Yahoo Finance and it is your responsibility to cache the data so as to avoid redundant requests.  
+The reason for disabling the cache has to do with the lack of guarantees regarding the provided data which can lead to inconsistencies for less popular instruments.  
 
-## How to run
-
-There are two ways you can use this library.
-
-* As a dependency of a dotnet application/class library.
-* Inside a `dotnet-interactive` notebook.
+Methods are made static to make it easier to use from interactive environments.  
+That is also the reason why there aren't a lot of options for Dependencies Injection of, for example, logging.  
+To further simplify the use of methods in the package, arguments are passed using basic types like `string` and `int32`.

docfx_project/toc.yml

@@ -1,5 +1,5 @@
-#- name: Articles
-#  href: articles/
+- name: Tutorials
+  href: tutorials/
 - name: Api Documentation
   href: api/
   homepage: api/index.md

docfx_project/tutorials/dotnet-interactive.md

@@ -0,0 +1,57 @@
+## Tesla earnings
+
+The code blocks in this tutorials should be executed as part of a `dotnet-interactive` notebook.  
+
+In this example, we look at the price action before and after the last Tesla earnings. The number of days analyzed is always even, the first half of the days are from before the earnings call and the reminder are from after the earnings results have been released.
+
+
+Although `CsvHelper` and `ServiceStack.Text` should be installed as transient dependencies, they are not, so in the notebook, they have to be installed individually.
+
+```csharp
+#r "nuget: CosminSanda.Finance"
+#r "nuget: XPlot.Plotly.Interactive"
+#r "nuget: CsvHelper"
+#r "nuget: ServiceStack.Text"
+```
+
+Get an asceding ordered list of all Tesla earnings dates.  
+
+```csharp
+var earnings = await EarningsCalendar.GetPastEarningsDates("TSLA");
+```
+
+We'll exemplify using just the latest earnings call date.
+
+```csharp
+var lastDate = earnings.Last();
+```
+
+Get the OHLC data for 5 days before and 5 days after the earnings call.  
+The earnings call can take place before market open (in which case the date of the earnings call is included in the last 5 days) or after market close (in which case the date of the earnings call is included in the first 5 days).
+
+```csharp
+var quotes = await Quotes.GetQuotesAround("TSLA", lastDate, 5);
+```
+
+Use a charting library to vizualise the data and get a feel of how the earnings call expectations and actual results influence the price action.
+
+In the case of the Tesla earnings release on 20th of July 2022, it's obvious that the call happened after market close, so the 20th is part of the "before earnings" half of the cancles.
+
+```csharp
+var chart = Chart
+    .Candlestick(quotes.Select(o => new Tuple<string, double, double, double, double>(
+        o.Date.ToDateTime(TimeOnly.Parse("10:00 PM")).ToString("yyyy-MM-dd"),
+        o.Open,
+        o.High,
+        o.Low,
+        o.Close
+    )));
+chart.WithLayout(new Layout.Layout{
+    title=$"Tesla earnings on {lastDate.Date}"
+});
+chart
+```
+
+You should see something similar to this:
+
+![Tesla earnings call](../images/tesla.png)

docfx_project/tutorials/intro.md

@@ -0,0 +1 @@
+Here you can find end-to-end sample of using the library.

docfx_project/tutorials/toc.yml

@@ -0,0 +1,4 @@
+- name: Introduction
+  href: intro.md
+- name: dotnet-interactive
+  href: dotnet-interactive.md

notebooks/demo.dib

@@ -1,39 +1,65 @@
 #!markdown
 
-#### Install the latest version of the package
+## Tesla earnings
+
+In this example, we look at the price action before and after the last Tesla earnings. The number of days analyzed is always even, the first half of the days are from before the earnings call and the reminder are from after the earnings results have been released.
+
+
+Although `CsvHelper` and `ServiceStack.Text` should be installed as transient dependencies, they are not, so in the notebook, they have to be installed individually.
 
 #!csharp
 
 #r "nuget: CosminSanda.Finance"
 #r "nuget: XPlot.Plotly.Interactive"
+#r "nuget: CsvHelper"
+#r "nuget: ServiceStack.Text"
 
 #!csharp
 
 using XPlot.Plotly;
 using CosminSanda.Finance;
 
+#!markdown
+
+Get an asceding ordered list of all Tesla earnings dates.
+
 #!csharp
 
-var earnings = await EarningsCalendar.GetPastEarningsDates("TWTR");
+var earnings = await EarningsCalendar.GetPastEarningsDates("TSLA");
+
+#!markdown
+
+We'll exemplify using just the latest earnings call date.
 
 #!csharp
 
 var lastDate = earnings.Last();
 
+#!markdown
+
+Get the OHLC data for 5 days before and 5 days after the earnings call. The earnings call can take place before market open (in which case the date of the earnings call is included in the last 5 days) or after market close (in which case the date of the earnings call is included in the first 5 days).
+
 #!csharp
 
-var quotes = await Quotes.GetQuotesAround("TWTR", lastDate, 3);
+var quotes = await Quotes.GetQuotesAround("TSLA", lastDate, 5);
+
+#!markdown
+
+Use a charting library to vizualise the data and get a feel of how the earnings call expectations and actual results influence the price action.
+
+In the case of the Tesla earnings release on 20th of July 2022, it's obvious that the call happened after market close, so the 20th is part of the "before earnings" half of the cancles.
 
 #!csharp
 
-Chart
+var chart = Chart
     .Candlestick(quotes.Select(o => new Tuple<string, double, double, double, double>(
         o.Date.ToDateTime(TimeOnly.Parse("10:00 PM")).ToString("yyyy-MM-dd"),
         o.Open,
         o.High,
         o.Low,
         o.Close
-    )))
-    .WithLayout(new Layout.Layout{
-        title="OHLC"
-    })
+    )));
+chart.WithLayout(new Layout.Layout{
+    title=$"Tesla earnings on {lastDate.Date}"
+});
+chart