Merge pull request #1 from Odotocodot/develop

Version 1.1.0

.gitignore

@@ -360,4 +360,7 @@ MigrationBackup/
 .ionide/
 
 # Fody - auto-generated XML schema
-FodyWeavers.xsd
+FodyWeavers.xsd
+
+# JetBrains
+.idea/

CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## [1.1.0] - 2024-06-04
+
+### Added
+- Exposed OneNote COM object to allow for more advanced operations if needed.
+- Added and refactored parser tests.
+- Exposed UpdatePageContent method.
+- LinqPad samples
+- Added FindByID method to find a hierarchy item by its ID (Currently slow).
+
+### Changed
+- Updated logo!
+- Renamed IOneNoteItemExtensions to OneNoteItemExtensions.
+- OneNoteNotebook.Notebook returns itself rather than null.
+- Updated documentation to include examples and more information on the library.
+- The methods that create hierarchy items e.g. CreatePage, CreateSection, CreateSectionGroup, CreateNotebook now return the ID of the created item. Can be used with the new FindByID.
+
+## [1.0.0] - 2023-10-16

Documentation/api/index.md

@@ -1,2 +1,5 @@
-# PLACEHOLDER
-TODO: Add .NET projects to the *src* folder and run `docfx` to generate **REAL** *API Documentation*!
+# API Reference
+Select a class on the left hand side to view its documentation.
+
+An overview of the library can be seen in the class diagram below.
+![class diagram](~/images/class_diagram.png)

Documentation/articles/changelog.md

@@ -0,0 +1 @@
+[!INCLUDE [CHANGELOG](../../CHANGELOG.md)]

Documentation/articles/extra_information.md

@@ -0,0 +1,31 @@
+# Additional Information
+
+### The Hierarchy Conundrum
+
+Currently, the full hierarchy is returned when calling `OneNoteApplication.GetNotebooks()`. 
+Which means depending on the number of notebooks, section groups, sections and pages you have it can take a significant amount of time.
+
+Furthermore, when calling `OneNoteApplication.FindPages()` the hierarchy returned is _partially full_. 
+The pages returned have references all the way to the notebooks that owns them, but those notebooks will not have all there 
+descendants (section groups, sections and pages) present, only the ones related to the pages returned.
+
+This can lead to weird scenarios such as:
+```csharp
+var page = OneNoteApplication.FindPages("A unique page").First();
+var searchNotebook = page.Notebook;
+//or alternatively
+IOneNoteItem item = page;
+while (item is not OneNoteNotebook)
+{
+    item = item.Parent;
+}
+
+Console.WriteLine(item == searchNotebook); //Prints TRUE
+
+var getAllNotebook = OneNoteApplication.GetNotebooks().First(n => n.Name == searchNotebook.Name);
+//Here's where things get weird
+Console.WriteLine(searchNotebook == getAllNotebook); //Prints FALSE
+Console.WriteLine(searchNotebook.ID == getAllNotebook.ID); //Prints TRUE
+Console.WriteLine(searchNotebook.Children.Traverse().Count() ==
+                  getAllNotebook.Children.Traverse().Count()); //Prints FALSE
+```

Documentation/articles/installation.md

@@ -0,0 +1,24 @@
+# Installation
+#### Step 1
+First make sure you have a local installation of OneNote, such as [OneNote](https://apps.microsoft.com/detail/xpffzhvgqwwlhb?hl=en-gb&gl=GB) (previously OneNote 2016) or [OneNote for Windows 10](https://www.microsoft.com/store/productId/9WZDNCRFHVJL?ocid=pdpshare).
+
+#### Step 2
+Create a console application, or open an existing one.
+
+#### Step 3
+Install the library from NuGet [here](https://www.nuget.org/packages/Odotocodot.OneNote.Linq/) or run the following command in your project directory:
+```
+dotnet add package Odotocodot.OneNote.Linq
+```
+
+#### Step 4
+Next code away!
+
+#### Afterword
+See [samples](samples.md) for examples on how to use the library.
+
+> [!IMPORTANT]
+> This library only works for local versions of OneNote, and does not make use of the Microsoft Graph API.
+
+> [!IMPORTANT]
+> This library is windows only as it uses COM Interop to interact with OneNote.

Documentation/articles/memory_management.md

@@ -0,0 +1,36 @@
+# Memory Management
+
+A COM object is required to use the OneNote Interop API, by default this is acquired lazily, i.e. the first time you call a method that requires a COM object, the library gets one.
+
+However, acquiring a COM object is _slow_ and once retrieved, it is visible in the Task Manager as shown below.
+
+![task manager screenshot](~/images/task_manager.png)
+
+If you want to choose when this operation occurs, you can call ``OneNoteApplication.InitComObject()`` to forcible acquire the COM object (it does nothing if one has already been attained).
+
+To free up the memory that the COM object takes up, rather than wait for your application to exit you can call  ``OneNoteApplication.ReleaseComObject()``.
+
+See below for an example.
+
+```csharp
+//Get the COM object
+OneNoteApplication.InitComObject();
+
+//Do stuff e.g.
+OneNoteNotebook notebooks = OneNoteApplication.GetNotebooks();
+
+foreach (var notebook in notebooks)
+{
+    Console.WriteLine(notebook.Name)
+}
+
+IEnumerable<OneNotePage> pages = notebooks.Traverse(n => n.Children.Count() > 3).GetPages();
+
+foreach (var page in pages)
+{
+    Console.WriteLine(page.Section.Name);
+}
+
+//Release the COM object to free memory
+OneNoteApplication.ReleaseComObject()
+```

Documentation/articles/samples.md

@@ -0,0 +1,40 @@
+# Samples and Examples
+
+The library's original purpose was for the OneNote [Flow Launcher](https://www.flowlauncher.com/) plugin available [here](https://github.com/Odotocodot/Flow.Launcher.Plugin.OneNote). This plugin itself has several good examples of how to use the library.
+
+The examples below are not exactly best practices, but they should give you a good starting point!
+
+They can also be found in the free and paid version of [LinqPad](https://www.linqpad.net/) for easy viewing! (Though be weary of the [Create Page](#create-pages-in-sections-with-less-than-2-pages) example as it will create a pages in your OneNote!)
+### Get Recent Pages
+
+[!code-csharp[](../../linqpad-samples/RecentPages.linq#L7-L18)]
+
+### Get All Items in Recycle Bins
+
+[!code-csharp[](../../linqpad-samples/RecycleBinItems.linq#L7-L26)]
+
+### Search for a Page and Open Its Section
+
+[!code-csharp[](../../linqpad-samples/OpenSection.linq#L7-L17)]
+
+### Create Pages in Sections With Less Than 2 Pages
+
+> [!WARNING]
+> If you decide to run this code it will create pages (potentially hundreds :dizzy_face:) in your OneNote!
+
+```csharp
+//IF YOU RUN THIS IT WILL CREATE A PAGES IN YOUR ONENOTE!
+var newPageName = "Hopefully a very unique and specific title!";
+var sections = OneNoteApplication.GetNotebooks()
+    .Traverse(i => i is OneNoteSection)
+    .Cast<OneNoteSection>()
+    .Where(s => s.Pages.Count() <= 1);
+foreach (var section in sections)
+{
+    OneNoteApplication.CreatePage(section, newPageName, false);
+}
+```
+
+
+
+

Documentation/articles/toc.yml

@@ -1,2 +1,14 @@
-- name: Introduction
-  href: intro.md
+- name: Overview
+  href: ../index.md
+- name: Installation
+  href: installation.md
+- name: Samples
+  href: samples.md
+- name: Memory Management
+  href: memory_management.md
+- name: Additional Information
+  href: extra_information.md
+
+- name: Changelog
+  href: changelog.md
+

Documentation/docfx.json

@@ -10,15 +10,13 @@
         }
       ],
       "dest": "api",
-      "outputFormat": "mref",
-      "includePrivateMembers": false,
       "disableGitFeatures": false,
       "disableDefaultFilter": false,
-      "noRestore": false,
+      "outputFormat": "apiPage",
       "namespaceLayout": "flattened",
       "memberLayout": "separatePages",
-      "EnumSortOrder": "alphabetic",
-      "allowCompilationErrors": false
+      "shouldSkipMarkup": false,
+      "useCompatibilityFileName": false
     }
   ],
   "build": {
@@ -51,23 +49,31 @@
       "_appFaviconPath": "images/favicon.ico",
       "_appLogoPath": "images/logo.svg",
       "_appName": "LINQ to OneNote",
-      "_appFooter": "© 2023 Odotocodot   |   Made with <a href=\"https://dotnet.github.io/docfx\">docfx</a>",
       "_enableSearch": true,
-      "_disableSideFilter": false,
-      "_disableNavbar": false,
-      "_disableAffix": false,
-      "_enableNewTab": true,
       "_disableContribution": true,
-      "_disableBreadcrumb": false
+      "_disableBreadcrumb" : false,
+      "_disableNavbar": false,
+      "_appFooter": "© 2023-2024 Odotocodot   |   Made with <a href=\"https://dotnet.github.io/docfx\">docfx</a>",
     },
     "globalMetadataFiles": [],
     "fileMetadataFiles": [],
     "template": [
       "default",
       "modern"
     ],
+    "sitemap": {
+      "baseUrl": "https://odotocodot.github.io/Linq2OneNote/",
+      "options": {
+        "changefreq": "yearly",
+        "priority": 0.8
+      }
+    },
     "postProcessors": [],
     "keepFileLink": false,
-    "disableGitFeatures": false
+    "disableGitFeatures": false,
+    "exportViewModel": false,
+    "noLangKeyword": false,
+    "markdownEngineName": "markdig",
+    "cleanupCacheHistory": false
   }
 }