Merge pull request #30 from AngleSharp/devel

Release 0.16.0

.github/workflows/ci.yml

@@ -5,8 +5,45 @@ on: [push, pull_request]
 env:
   GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
   NUGET_API_KEY: ${{ secrets.NUGET_API_KEY }}
+  DOCS_PATH: ${{ secrets.DOCS_PATH }}
+  DOCS_BRANCH: ${{ secrets.DOCS_BRANCH }}
 
 jobs:
+  can_document:
+    runs-on: ubuntu-latest
+    outputs:
+      value: ${{ steps.check_job.outputs.value }}
+    steps:
+      - name: Checks whether documentation can be built
+        id: check_job
+        run: |
+            echo "value: ${{ env.DOCS_PATH != null && github.ref == env.DOCS_BRANCH }}"
+            echo "::set-output name=value::${{ env.DOCS_PATH != null && github.ref == env.DOCS_BRANCH }}"
+
+  documentation:
+    needs: [can_document]
+    runs-on: ubuntu-latest
+    if: needs.can_document.outputs.value == 'true'
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Use Node.js
+      uses: actions/setup-node@v1
+      with:
+        node-version: "14.x"
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install Dependencies
+      run: |
+        cd $DOCS_PATH
+        npm install
+
+    - name: Deploy Doclet
+      run: |
+        cd $DOCS_PATH
+        npx pilet publish --fresh --url https://feed.piral.cloud/api/v1/pilet/anglesharp --api-key ${{ secrets.PIRAL_FEED_KEY }}
+
   linux:
     runs-on: ubuntu-latest
 
@@ -24,7 +61,7 @@ jobs:
 
     - name: Build
       run: |
-        if ($env:GITHUB_REF -eq "refs/heads/master") {
+        if ($env:GITHUB_REF -eq "refs/heads/main") {
           .\build.ps1 -Target Publish
         } elseif ($env:GITHUB_REF -eq "refs/heads/devel") {
           .\build.ps1 -Target PrePublish

.gitignore

@@ -75,6 +75,8 @@ artifacts/
 [Tt]ools/
 ![Tt]ools/packages.config
 TestResults/
+node_modules
+package-lock.json
 *.nuget.targets
 *.nuget.props
 *.nupkg

CHANGELOG.md

@@ -1,3 +1,9 @@
+# 0.16.0
+
+Released on Sunday, June 6 2021.
+
+- Updated to use AngleSharp 0.16
+
 # 0.15.0
 
 Released on Friday, April 23 2021.

docs/README.md

@@ -0,0 +1,5 @@
+# AngleSharp.Io Documentation
+
+We have more detailed information regarding the following subjects:
+
+- [API Documentation](tutorials/01-API.md)

docs/general/01-Basics.md

@@ -0,0 +1,109 @@
+---
+title: "Getting Started"
+section: "AngleSharp.Io"
+---
+# Getting Started
+
+## Requirements
+
+AngleSharp.Io comes currently in two flavors: on Windows for .NET 4.6 and in general targetting .NET Standard 2.0 platforms.
+
+Most of the features of the library do not require .NET 4.6, which means you could create your own fork and modify it to work with previous versions of the .NET-Framework.
+
+You need to have AngleSharp installed already. This could be done via NuGet:
+
+```ps1
+Install-Package AngleSharp
+```
+
+## Getting AngleSharp.Io over NuGet
+
+The simplest way of integrating AngleSharp.Io to your project is by using NuGet. You can install AngleSharp.Io by opening the package manager console (PM) and typing in the following statement:
+
+```ps1
+Install-Package AngleSharp.Io
+```
+
+You can also use the graphical library package manager ("Manage NuGet Packages for Solution"). Searching for "AngleSharp.Io" in the official NuGet online feed will find this library.
+
+## Setting up AngleSharp.Io
+
+To use AngleSharp.Io you need to add it to your `Configuration` coming from AngleSharp itself.
+
+### Requesters
+
+If you just want to use *all* available requesters provided by AngleSharp.Io you can do the following:
+
+```cs
+var config = Configuration.Default
+    .WithRequesters() // from AngleSharp.Io
+    .WithDefaultLoader(); // from AngleSharp
+```
+
+This will register all requesters. Alternatively, the requesters can be provided explicitly. They are located in the `AngleSharp.Io.Network` namespace and have names such as `DataRequester`.
+
+Requesters can make use of `HttpClientHandler` instances. Hence using it, e.g., with a proxy is as simple as the following snippet:
+
+```cs
+var handler = new HttpClientHandler
+{
+    Proxy = new WebProxy(myProxyHost, false),
+    PreAuthenticate = true,
+    UseDefaultCredentials = false,
+};
+
+var config = Configuration.Default
+    .WithRequesters(handler) // from AngleSharp.Io with a handler config
+    .WithDefaultLoader();
+```
+
+Alternatively, if you don't want to add all possible requesters, you can also just add a single requester from AngleSharp.Io:
+
+```cs
+var config = Configuration.Default
+    .With(new HttpClientRequester()) // only requester
+    .WithDefaultLoader();
+```
+
+In the code above we now only have a single requester - the `HttpClientRequester` coming from AngleSharp.Io. If we have an `HttpClient` already used somewhere we can actually re-use it:
+
+```cs
+var config = Configuration.Default
+    .With(new HttpClientRequester(myHttpClient)) // re-using the HttpClient instance
+    .WithDefaultLoader();
+```
+
+### Cookies
+
+To get improved cookie support, e.g., do
+
+```cs
+var config = Configuration.Default
+    .WithTemporaryCookies(); // Uses memory cookies
+```
+
+or if you want to have persistent cookies you can use:
+
+```cs
+var syncPath = $"Environment.GetFolderPath(Environment.SpecialFolder.UserProfile)\\anglesharp.cookies";
+var config = Configuration.Default
+    .WithPersistentCookies(syncPath); // Uses sync cookies against the given path
+```
+
+Alternatively, the new overloads for the `WithCookies` extension method can be used.
+
+### Downloads
+
+AngleSharp.Io offers you the possibility of a simplified downloading experience. Just use `WithStandardDownload` to redirect resources to a callback.
+
+In the simplest case you can write:
+
+```cs
+var config = Configuration.Default
+    .WithStandardDownload((fileName, content) =>
+    {
+        // store fileName with the content stream ...
+    });
+```
+
+Alternatively, use `WithDownload`, which allows you to distinguish also on the provided MIME type.

docs/tutorials/01-API.md

@@ -0,0 +1,7 @@
+---
+title: "API Documentation"
+section: "AngleSharp.Io"
+---
+# API Documentation
+
+(tbd)

docs/tutorials/02-Examples.md

@@ -0,0 +1,11 @@
+---
+title: "Examples"
+section: "AngleSharp.Io"
+---
+# Example Code
+
+This is a (growing) list of examples for every-day usage of AngleSharp.Io.
+
+## Some Example
+
+(tbd)

docs/tutorials/03-Questions.md

@@ -0,0 +1,9 @@
+---
+title: "Questions"
+section: "AngleSharp.Io"
+---
+# Frequently Asked Questions
+
+## What to ask?
+
+(tbd)

src/AngleSharp.Io.Docs/docs.config.json

@@ -0,0 +1,28 @@
+{
+  "name": "AngleSharp.Io",
+  "author": "Florian Rappl",
+  "branch": "devel",
+  "repositoryUrl": "https://github.com/AngleSharp/AngleSharp.Io",
+  "rootDir": "../../",
+  "outputDir": "./dist",
+  "sitemap": {
+    "general": {
+      "sections": [
+        {
+          "generator": "markdown",
+          "segment": "io",
+          "dir": "general"
+        }
+      ]
+    },
+    "docs": {
+      "sections": [
+        {
+          "generator": "markdown",
+          "segment": "io",
+          "dir": "tutorials"
+        }
+      ]
+    }
+  }
+}

src/AngleSharp.Io.Docs/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@anglesharp/io",
+  "version": "0.16.0",
+  "preview": true,
+  "description": "The doclet for the AngleSharp.Io documentation.",
+  "keywords": [
+    "pilet"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@anglesharp/website": "1.0.0",
+    "@types/react": "^17.0.5",
+    "@types/react-dom": "^17.0.5",
+    "@types/react-router": "latest",
+    "@types/react-router-dom": "^5.1.7",
+    "@types/node": "^15.3.0",
+    "typescript": "^4.2.4",
+    "@dbeining/react-atom": "4.1.19",
+    "@libre/atom": "1.3.3",
+    "history": "4.10.1",
+    "react": "17.0.2",
+    "react-dom": "17.0.2",
+    "react-router": "5.2.0",
+    "react-router-dom": "5.2.0",
+    "tslib": "2.2.0",
+    "path-to-regexp": "1.8.0",
+    "piral-cli": "^0.13.3-pre.2480",
+    "piral-cli-parcel": "^0.13.3-pre.2480"
+  },
+  "peerDependencies": {
+    "@dbeining/react-atom": "*",
+    "@libre/atom": "*",
+    "history": "*",
+    "react": "*",
+    "react-dom": "*",
+    "react-router": "*",
+    "react-router-dom": "*",
+    "tslib": "*",
+    "path-to-regexp": "*",
+    "@anglesharp/website": "*"
+  },
+  "scripts": {
+    "start": "pilet debug",
+    "build": "pilet build",
+    "upgrade": "pilet upgrade"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "piral": {
+    "comment": "Keep this section to use the Piral CLI.",
+    "name": "@anglesharp/website"
+  },
+  "peerModules": [
+    "piral-docs-tools/components"
+  ]
+}

src/AngleSharp.Io.Docs/src/index.tsx

@@ -0,0 +1,7 @@
+import { PiletApi } from 'piral-docs-tools';
+
+const createDoclet = require('piral-docs-tools/doclet');
+
+export function setup(api: PiletApi) {
+  createDoclet(api);
+}

src/AngleSharp.Io.Docs/tsconfig.json

@@ -0,0 +1,25 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "noImplicitAny": false,
+    "removeComments": false,
+    "noLib": false,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "target": "es6",
+    "sourceMap": true,
+    "outDir": "./dist",
+    "skipLibCheck": true,
+    "lib": ["dom", "es2018"],
+    "moduleResolution": "node",
+    "module": "esnext",
+    "jsx": "react",
+    "importHelpers": true
+  },
+  "include": [
+    "./src"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

src/AngleSharp.Io.Tests/Cookie/ParsingTests.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Tests.Cookie
 {
+    using AngleSharp.Dom;
     using AngleSharp.Io.Cookie;
     using NUnit.Framework;
     using System;

src/AngleSharp.Io.Tests/Network/AboutTests.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Tests.Network
 {
+    using AngleSharp.Dom;
     using AngleSharp.Io.Network;
     using NUnit.Framework;
     using System.Collections.Generic;

src/AngleSharp.Io.Tests/Network/CookieHandlingTests.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Tests.Network
 {
+    using AngleSharp.Dom;
     using NUnit.Framework;
     using System;
     using System.Threading.Tasks;

src/AngleSharp.Io.Tests/Network/DataRequesterTests.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Tests.Network
 {
+    using AngleSharp.Dom;
     using AngleSharp.Io;
     using AngleSharp.Io.Network;
     using AngleSharp.Text;

src/AngleSharp.Io.Tests/Network/HttpClientRequesterTests.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Tests.Network
 {
+    using AngleSharp.Dom;
     using AngleSharp.Io.Network;
     using AngleSharp.Io.Tests.Network.Mocks;
     using FluentAssertions;

src/AngleSharp.Io.Tests/Network/Mocks/HttpMockState.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Tests.Network.Mocks
 {
+    using AngleSharp.Dom;
     using AngleSharp.Io.Network;
     using System;
     using System.Collections.Generic;

src/AngleSharp.Io.Tests/Network/ResponseTests.cs

@@ -1,5 +1,6 @@
 namespace AngleSharp.Io.Network.Tests.Integration
 {
+    using AngleSharp.Dom;
     using NUnit.Framework;
     using System.Collections.Generic;