Merge pull request #79 from AngleSharp/devel

Release 0.15.0

.github/CONTRIBUTING.md

@@ -26,47 +26,50 @@ Discussion of issues should be placed transparently in the issue tracker here on
 
 * [AngleSharp.Core](https://github.com/AngleSharp/AngleSharp/issues/)
 * [AngleSharp.Css](https://github.com/AngleSharp/AngleSharp.Css/issues/)
+* [AngleSharp.Diffing](https://github.com/AngleSharp/AngleSharp.Diffing/issues/)
 * [AngleSharp.Io](https://github.com/AngleSharp/AngleSharp.Io/issues/)
 * [AngleSharp.Js](https://github.com/AngleSharp/AngleSharp.Js/issues/)
 * [AngleSharp.Xml](https://github.com/AngleSharp/AngleSharp.Xml/issues/)
+* [AngleSharp.XPath](https://github.com/AngleSharp/AngleSharp.XPath/issues/)
+* [AngleSharp.Wasm](https://github.com/AngleSharp/AngleSharp.Wasm/issues/)
 
 ### Modifying the code
 
 AngleSharp and its libraries uses features from the latest versions of C# (e.g., C# 7). You will therefore need a C# compiler that is up for the job.
 
 1. Fork and clone the repo.
-2. First try to build the AngleSharp.Core libray and see if you get the tests running.
+2. First try to build the AngleSharp.Core library and see if you get the tests running.
 3. You will be required to resolve some dependencies via NuGet.
 
 AngleSharp itself does not have dependencies, however, the tests are dependent on NUnit.
 
-The build system of AngleSharp uses Cake. A bootstrap script (build.ps1 for Windows or build.sh for *nix systems) is included. Note, that at the moment AngleSharp may require NuGet 3.5, which looks for MSBuild pre-15, i.e., before Visual Studio 2017 on Windows systems. We aim to drop this requirement enitirely soon.
+The build system of AngleSharp uses Cake. A bootstrap script (build.ps1 for Windows or build.sh for *nix systems) is included. Note, that at the moment AngleSharp may require NuGet 3.5, which looks for MSBuild pre-15, i.e., before Visual Studio 2017 on Windows systems. We aim to drop this requirement entirely soon.
 
 ### Code Conventions
 
 Most parts in the AngleSharp project are fairly straight forward. Among these are:
 
-- Always use statement blocks for control statements, e.g., in a for-loop, if-condition, ...
-- You may use a simple (throw) statement in case of enforcing contracts on argument
-- Be explicit about modifiers (some files follow an older convention of the code base, but we settled on the explicit style)
+* Always use statement blocks for control statements, e.g., in a for-loop, if-condition, ...
+* You may use a simple (throw) statement in case of enforcing contracts on argument
+* Be explicit about modifiers (some files follow an older convention of the code base, but we settled on the explicit style)
 
 There are a couple of rules, which are definitely not standard, but highly recommended for consistency and readability:
 
-- AngleSharp uses the RHS convention, where types are always put on the right hand side if possible, i.e., preferring `var` under all circumstances
-- A single empty line between two non-simple statements (e.g., for-loop and if-condition) should be inserted
-- Types are preferred to keywords (`String` instead of `string` or `Int32` instead of `int`)
-- `using` statements must be inside the namespace declaration
+* AngleSharp uses the RHS convention, where types are always put on the right hand side if possible, i.e., preferring `var` under all circumstances
+* A single empty line between two non-simple statements (e.g., for-loop and if-condition) should be inserted
+* Types are preferred to keywords (`String` instead of `string` or `Int32` instead of `int`)
+* `using` statements must be inside the namespace declaration
 
 ### Development Workflow
 
 1. If no issue already exists for the work you'll be doing, create one to document the problem(s) being solved and self-assign.
 2. Otherwise please let us know that you are working on the problem. Regular status updates (e.g. "still in progress", "no time anymore", "practically done", "pull request issued") are highly welcome.
-2. Create a new branch—please don't work in the `master` branch directly. It is reserved for releases. We recommend naming the branch to match the issue being addressed (`feature/#777` or `issue-777`).
-3. Add failing tests for the change you want to make. Tests are crucial and should be taken from W3C (or other specification).
-4. Fix stuff. Always go from edge case to edge case.
-5. All tests should pass now. Also your new implementation should not break existing tests.
-6. Update the documentation to reflect any changes. (or document such changes in the original issue)
-7. Push to your fork or push your issue-specific branch to the main repository, then submit a pull request against `devel`.
+3. Create a new branch—please don't work in the `master` branch directly. It is reserved for releases. We recommend naming the branch to match the issue being addressed (`feature/#777` or `issue-777`).
+4. Add failing tests for the change you want to make. Tests are crucial and should be taken from W3C (or other specification).
+5. Fix stuff. Always go from edge case to edge case.
+6. All tests should pass now. Also your new implementation should not break existing tests.
+7. Update the documentation to reflect any changes. (or document such changes in the original issue)
+8. Push to your fork or push your issue-specific branch to the main repository, then submit a pull request against `devel`.
 
 Just to illustrate the git workflow for AngleSharp a little bit more we've added the following graphs.
 
@@ -76,19 +79,19 @@ Here we now created a new branch called `devel`. This is the development branch.
 
 Now active work is supposed to be done. Therefore a new branch should be created. Let's create one:
 
-```
+```sh
 git checkout -b feature/#777
 ```
 
 There may be many of these feature branches. Most of them are also pushed to the server for discussion or synchronization.
 
-```
+```sh
 git push -u origin feature/#777
 ```
 
 Now feature branches may be closed when they are done. Here we simply merge with the feature branch(es). For instance the following command takes the `feature/#777` branch from the server and merges it with the `devel` branch.
 
-```
+```sh
 git checkout devel
 git pull
 git pull origin feature/#777
@@ -97,7 +100,7 @@ git push
 
 Finally, we may have all the features that are needed to release a new version of AngleSharp. Here we tag the release. For instance for the 1.0 release we use `v1.0`.
 
-```
+```sh
 git checkout master
 git merge devel
 git tag v1.0
@@ -109,12 +112,11 @@ git tag v1.0
 
 The following files should not be edited directly in the current repository, but rather in the `AngleSharp.GitBase` repository. They are then synced via `git pull` from a different remote.
 
-```
+```plaintext
 .editorconfig
 .gitignore
 .gitattributes
 .github/*
-appveyor.yml
 build.ps1
 build.sh
 tools/anglesharp.cake
@@ -124,7 +126,7 @@ LICENSE
 
 To sync manually:
 
-```
+```sh
 git remote add gitbase [email protected]:AngleSharp/AngleSharp.GitBase.git
 git pull gitbase master
 ```

.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# These are supported funding model platforms
+
+github: FlorianRappl
+custom: https://salt.bountysource.com/teams/anglesharp

.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+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
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Build
+      run: ./build.sh
+
+  windows:
+    runs-on: windows-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Build
+      run: |
+        if ($env:GITHUB_REF -eq "refs/heads/main") {
+          .\build.ps1 -Target Publish
+        } elseif ($env:GITHUB_REF -eq "refs/heads/devel") {
+          .\build.ps1 -Target PrePublish
+        } else {
+          .\build.ps1
+        }

.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.15.0
+
+Released on Sunday, June 12 2021.
+
+- Updated to use AngleSharp 0.15
+
 # 0.14.0
 
 Released on Tuesday, March 31 2020.

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013 - 2020 AngleSharp
+Copyright (c) 2013 - 2021 AngleSharp
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

build.cake

@@ -6,7 +6,6 @@ var frameworks = new Dictionary<String, String>
     { "net46", "net46" },
     { "net461", "net461" },
     { "net472", "net472" },
-    { "netstandard1.3", "netstandard1.3" },
     { "netstandard2.0", "netstandard2.0" },
 };
 

build.ps1

@@ -26,17 +26,17 @@ $NUGET_OLD_URL = "https://dist.nuget.org/win-x86-commandline/v3.5.0/nuget.exe"
 # Should we use experimental build of Roslyn?
 $UseExperimental = "";
 if ($Experimental.IsPresent) {
-    $UseExperimental = "-experimental"
+    $UseExperimental = "--experimental"
 }
 
 # Is this a dry run?
 if ($WhatIf.IsPresent) {
-    $UseDryRun = "-dryrun"
+    $UseDryRun = "--dryrun"
 }
 
 # Should we use mono?
 if ($Mono.IsPresent) {
-    $UseMono = "-mono"
+    $UseMono = "--mono"
 }
 
 # Try download NuGet.exe if do not exist.
@@ -77,5 +77,5 @@ if (!(Test-Path $CAKE_EXE)) {
 }
 
 # Start Cake
-Invoke-Expression "$CAKE_EXE `"$Script`" -target=`"$Target`" -configuration=`"$Configuration`" -verbosity=`"$Verbosity`" $UseMono $UseDryRun $UseExperimental $ScriptArgs"
+Invoke-Expression "$CAKE_EXE `"$Script`" --target=`"$Target`" --configuration=`"$Configuration`" --verbosity=`"$Verbosity`" $UseMono $UseDryRun $UseExperimental $ScriptArgs"
 exit $LASTEXITCODE

build.sh

@@ -27,7 +27,7 @@ for i in "$@"; do
         -t|--target) TARGET="$2"; shift ;;
         -c|--configuration) CONFIGURATION="$2"; shift ;;
         -v|--verbosity) VERBOSITY="$2"; shift ;;
-        -d|--dryrun) DRYRUN="-dryrun" ;;
+        -d|--dryrun) DRYRUN="--dryrun" ;;
         --version) SHOW_VERSION=true ;;
         --) shift; SCRIPT_ARGUMENTS+=("$@"); break ;;
         *) SCRIPT_ARGUMENTS+=("$1") ;;
@@ -87,7 +87,7 @@ fi
 
 # Start Cake
 if $SHOW_VERSION; then
-    exec mono $CAKE_EXE -version
+    exec mono $CAKE_EXE --version
 else
-    exec mono $CAKE_EXE $SCRIPT -verbosity=$VERBOSITY -configuration=$CONFIGURATION -target=$TARGET $DRYRUN "${SCRIPT_ARGUMENTS[@]}"
+    exec mono $CAKE_EXE $SCRIPT --verbosity=$VERBOSITY --configuration=$CONFIGURATION --target=$TARGET $DRYRUN "${SCRIPT_ARGUMENTS[@]}"
 fi

docs/README.md

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

docs/general/01-Basics.md

@@ -0,0 +1,50 @@
+---
+title: "Getting Started"
+section: "AngleSharp.Js"
+---
+# Getting Started
+
+## Requirements
+
+AngleSharp.Js 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.Js over NuGet
+
+The simplest way of integrating AngleSharp.Js to your project is by using NuGet. You can install AngleSharp.Js by opening the package manager console (PM) and typing in the following statement:
+
+```ps1
+Install-Package AngleSharp.Js
+```
+
+You can also use the graphical library package manager ("Manage NuGet Packages for Solution"). Searching for "AngleSharp.Js" in the official NuGet online feed will find this library.
+
+## Setting up AngleSharp.Js
+
+To use AngleSharp.Js you need to add it to your `Configuration` coming from AngleSharp itself.
+
+If you just want a configuration *that works* you should use the following code:
+
+```cs
+var config = Configuration.Default
+    .WithJs(); // from AngleSharp.Js
+```
+
+This will register a scripting engine for JS files. The JS parsing options and more could be set with parameters of the `WithJs` method.
+
+You can also use this part with a console for logging. The call for this is `WithConsoleLogger`, e.g.,
+
+```cs
+var config = Configuration.Default
+    .WithJs()
+    .WithConsoleLogger(ctx => new MyConsoleLogger(ctx));
+```
+
+in the previous example `MyConsoleLogger` refers to a class implementing the `IConsoleLogger` interface. Examples of classes implementing this interface are available in our [samples repository](https://github.com/AngleSharp/AngleSharp.Samples).

docs/tutorials/01-API.md

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

docs/tutorials/02-Examples.md

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

docs/tutorials/03-Questions.md

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