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.
Configuration expects a connection string in the appsettings at
Data:DanglDocuSqlConnection:ConnectionString and two variables,
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.
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.
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
<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:
PathToFileis missing, a redirect is returned pointing to the entry point, e.g.
- If the
Versionis 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-beta1is requested but not present, if
1.0.0is present, it gets redirected to it. This keeps old urls from becoming unavailable
PathToFileis pointing to a non-existing file, a redirect to the entry point is returned
- Project assets can either be access via
Responses for project files have two different
3600(1 hour) if the version accessed is
604800(7 days) if any other version is accessed