Merge pull request #54 from WebFreak001/material-docs

replace everything with mkdocs (customized material theme)

Author: adamdruppe

.editorconfig

@@ -1,9 +1,9 @@
 root = true
 
-[*.{c,css,h,d,di,dd,dt,js,json}]
+[*.md]
 end_of_line = lf
 insert_final_newline = true
-indent_style = tab
+indent_style = space
 indent_size = 4
 trim_trailing_whitespace = true
 charset = utf-8

.gitignore

@@ -1,7 +1,2 @@
-/.project
-/.dub
-/__test__library__
-/dub-docs
-*.exe
-log.txt
-settings.json
+site/
+docs/cli-reference/

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "dub"]
+	path = dub
+	url = https://github.com/dlang/dub.git

README.md

@@ -5,14 +5,32 @@ Documentation for [dub](https://github.com/dlang/dub/) packages, see <https://du
 
 For the package registry, see https://code.dlang.org
 
-How to build & run locally
---------------------------
+## Contributing
+
+The documentation should be written using clear english, preferably avoiding addressing the reader with `"you"`, but rather using the passive form.
+
+The "dub-guide" folder (called DUB Guide) should contain quick summaries for the experienced user to quickly look up features, but also for the casual user to understand how most things work. Explanation should be kept short and concise. Whenever there are things that might not be completely clear, example images, CLI output or full project file structures should be provided.
+
+The "dub-reference" folder (called DUB Reference) should contain everything there is to know about DUB for the user. Everything should try to contain example recipes, example code, example output, so users know what to expect using things.
+
+Try not to duplicate information from the guide and the reference, but rather give short summaries in the guide and link to the reference for more in-depth explanation.
+
+The CLI reference is auto-generated and can be improved by improving the man page generator in the DUB project. (currently the markdown output is not yet PRd / merged into master there, so try to wait a little bit for this first)
+
+The intro pages should show everything to get started and not much more, to not overwhelm the user.
+
+### Local development
+
+To work on docs locally:
 
 ```
-dub
+# you might want to create a virtualenv if you work with python or other mkdocs sites a lot
+python3 -m pip install -r requirements.txt
+mkdocs serve
 ```
 
-Pages
------
-Documentation under `views/` is written in `diet-ng` template format,
-see https://code.dlang.org/packages/diet-ng.
+and to build static pages to distribute:
+
+```
+mkdocs build
+```

docs/dub-guide/building.md

@@ -0,0 +1,47 @@
+# Building
+
+!!! note "Work-in-Progress Documentation"
+
+    The content on this page is not yet fully finished.
+
+    Tracking issue: <https://github.com/dlang/dub-docs/issues/57>
+
+For the command to build your application, see [`dub build`](../cli-reference/dub-build.md) and [`dub run`](../cli-reference/dub-run.md)
+
+```
+dub build
+```
+
+If you have multiple [configurations](../dub-reference/configurations.md) defined in your recipe, you might need to specify which configuration to build:
+
+```
+dub build --config=server
+```
+
+Or if you want to build a [sub-package](../dub-reference/subpackages.md), you can do so from the root package as well:
+
+```
+dub build :mysubpackage
+```
+
+## Running
+
+For all of the samples above, you can swap out `dub build` with [`dub run`](../cli-reference/dub-run.md) to both **build and run** your application in a single command line call.
+
+This only works for packages that have an `executable` [target type](../dub-reference/target_types.md), which may be [automatically inferred](../dub-reference/configurations.md#default-configuration) by `autodetect`.
+
+```
+dub run
+dub run --config=server
+dub run :mysubpackage
+```
+
+### Passing arguments to the application
+
+For any of the above `dub run` calls you can also specify your own command line arguments by separating DUB's arguments from your own using `--` between them:
+
+```
+dub run -- my app args
+dub run --config=server -- --config=ignored-by-dub
+dub run :mysubpackage -- works universally
+```

docs/dub-guide/contributing.md

@@ -0,0 +1,25 @@
+# Contributing to DUB
+
+## Contributing to the CLI tool
+
+You can find the source code for the DUB CLI tool ([dub(1)](../cli-reference/dub.md)) on GitHub:
+
+[https://github.com/dlang/dub](https://github.com/dlang/dub)
+
+Find the instructions to build from source in the README there or in the [installation](../getting-started/install.md) section in this documentation.
+
+## Contributing to the registry / website
+
+The registry / website source code for DUB ([https://code.dlang.org](https://code.dlang.org)) is available on GitHub:
+
+[https://github.com/dlang/dub-registry](https://github.com/dlang/dub-registry)
+
+For the registry you will need to setup a MongoDB server and setup a GitHub auth token to put into the server config for API requests.
+
+For more information see [Registries](../dub-reference/registries.md).
+
+## Contributing to this documentation
+
+The documentation pages you are reading right now are also available on GitHub:
+
+[https://github.com/dlang/dub-docs](https://github.com/dlang/dub-docs)

docs/dub-guide/plugins_dlls.md

@@ -0,0 +1,7 @@
+# Creating shared libraries / DLLs
+
+!!! note "Work-in-Progress Documentation"
+
+    The content on this page is not yet fully finished.
+
+    Tracking issue: <https://github.com/dlang/dub-docs/issues/62>

docs/dub-guide/publishing.md

@@ -0,0 +1,33 @@
+# Publishing packages
+
+## Creating the project
+
+To create a DUB compatible project, the easiest way is to use the dub executable. [`$ dub init myproject`](../cli-reference/dub-init.md) will create a new folder `myproject` that contains the recommended skeleton and a basic `dub.json` or `dub.sdl` file. Running [`$ dub`](../cli-reference/dub.md) from this directory will build and run the empty project.
+
+You should then adjust the package recipe (`dub.json` / `dub.sdl`) to fit the project. Especially the [authors], [copyright], [license] and [description] fields should be properly filled out before publishing. For details about the format of this file, see the [recipe page](../dub-reference/recipe.md).
+
+## Registering with the registry
+
+If you want to publish your project, simply put the contents into a repository and push it to [GitHub](https://github.com/), [GitLab](https://gitlab.com/) or [Bitbucket](https://bitbucket.org/). You can then [register an account](https://code.dlang.org/register) on DUB and register the package using your GitHub/GitLab/Bitbucket user name (or organization) and the project name. Anyone who adds the name of your project as a dependency to his/her package recipe will automatically have the contents of your git repository available to his/her project.
+
+## Version tags
+
+The repository will be monitored for changes and new version tags. To add a new version, just create a [git tag](todo-link-git-tag.md) with a name of the form `v1.2.3`, where `1.2.3` should be changed to the actual version number, following the [SemVer specification](https://semver.org). About twice per hour, the repository will be queried for new tags and any detected version will be made available on the registry.
+
+Furthermore, all named branches will be available as special rolling versions of the form `~master` (in case of the git "master" branch). However, those should never directly be used to refer to dependencies. Use those only in dub.selections.json (see [dub-select(1)](../cli-reference/dub-select.md)) or for version overrides (see [dub-add-override(1)](../cli-reference/dub-add-override.md)).
+
+## Private repositories
+
+The [DUB registry](https://github.com/dlang/dub-registry) project can also be used as a private service. The settings file can be configured with credentials for a private repository hosting service instance, so that packages are fetched from the LAN, or from a private cloud based repository. Once a private instance is set up, all DUB clients need to be configured to make use of it by adding a `"registryUrls": ["http://dubregistry.example.com/"]` field with the appropriate URL(s) to your [dub settings file](../dub-reference/settings.md).
+
+## Package Scoring
+
+Search results are sorted by relevance. Relevance is a combined metric of the package score and the full-text search score, see [searchPackages(query)](https://github.com/dlang/dub-registry/blob/01cc896df7a5fa48cf65/source/dubregistry/dbcontroller.d#L239-L258). At the moment the package score is a number between `0.0` and `5.0` based on the following metrics:
+
+- Recent downloads (~50% weight)
+- Repo stars (~25% weight)
+- Repo watchers (~25% weight)
+- Repo forks (~25% weight)
+- Repo open issues (~-25% weight)
+
+Each of those metrics is log-scaled relative to their average before they are combined and capped with a non-linear tanh. See [computeScore()](https://github.com/dlang/dub-registry/blob/01cc896df7a5fa48cf65/source/dubregistry/registry.d#L576-L617) for more details. We appreciate any support in improving the package score.