Dangl.WebDocumentation - Readme

This is a small web application to host generated project documentation in static html format. It allows to control access to a project, either by making projects publicly available or by enabling access to projects for specific users.
It does accept a zip file as input and will then make the content available to be browsable through the web. You can use, for example, Sharpdox to create html documentation for C# projects, zip the output and upload it as project.

Tests and code coverage reports are generated by running TestaAndCoverage.ps1 in the root directory.

Setup

Configuration expects a connection string in the appsettings at Data:DanglDocuSqlConnection:ConnectionString and two variables, AllowUserRegistration and SiteTitle. Upon deployment, the first user to register is granted the admin role. For other users, admin roles are assigned manually by an existing admin.

Configuration

Admins create and manage projects, set which users can access them and upload packages via the web interface.

Upload a package

Projects are expected in zip format. The zip archives content is copied on the server under the App_Data folder. Projects have a property defining which relative path to use initially, e.g. index.html.

Via the web interface

Admins can simply select Upload Package in the admin section for a project and upload a zip file.

Via the API

In the project edit section, the API key for a project is set, it is used for http uploads. Example with cURL:
curl -F "ApiKey=<YourApiKey>" -F "Version=<DocVersion>" -F "ProjectPackage=@\"<PathToZipPackage>\"" https://<YourDomain>/API/Projects/Upload

You can optionally supply the string parameter markdownChangelog to include a changelog for the release.

Asset File Upload

Similarily, you can use the web interface or the API to upload asset files. Asset files are simply downloads that can be attached to a specific project and version.

curl -F "ApiKey=<YourApiKey>" -F "Version=<DocVersion>" -F "AssetFile=@\"<PathToZipPackage>\"" https://<YourDomain>/API/ProjectAssets/Upload

Access a package

Project names are required to be unique for pretty urls. Access is routed via https://<YourDomain>/Projects/<ProjectName>/<Version>/<PathToIndex>

The <Version> parameter may be set to latest to display the most recent version of the package.

Conventions When Accessing Documentation

Project file urls have the following format:

https://<YourDomain>/Projects/<ProjectName>/<Version>/<PathToFile>

• If PathToFile is missing, a redirect is returned pointing to the entry point, e.g. https://docs.dangl-it.com/Projects/LightQuery/1.1.0 redirects to https://docs.dangl-it.com/Projects/LightQuery/1.1.0/index.html
• If the Version is not found but a higher version is present, it redirects to the newer version. This is useful when you want to delete documentations for prerelease versions. For example, 1.0.0-beta1 is requested but not present, if 1.0.0 is present, it gets redirected to it. This keeps old urls from becoming unavailable
• If PathToFile is pointing to a non-existing file, a redirect to the entry point is returned
• Project assets can either be access via /ProjectAssets/{projectName}/{version} or /ProjectAssets/{projectName}/latest

Response Caching

Responses for project files have two different Cache-Control headers:

• 3600 (1 hour) if the version accessed is latest
• 604800 (7 days) if any other version is accessed

License

View