You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Contribute section with Mermaid schemas and more structured approach (#2)
* docs(contribute): Update small and medium/large on main contribute page. Update small library page
* docs(contribute): Harmonize section titles for Medium/Large library workflow and structure
* docs(contribute): UpdateSmall Library Structure structure to include version directories
* feat(docs): contribute
- Updated medium/large library
- fixes/enhancement to contribute and small library
* fix(config): correct privacy URL in configuration file
* doc(contribute): Added Doc Site page, removed emoji, reduce number of info boxes
* Refactor code structure for aligning to defined standards
DAX Lib supports including a `README.md` file with your library to provide documentation, which will be displayed alongside your library on [daxlib.org](https://daxlib.org/). For smaller libraries, this is typically sufficient.
13
+
14
+
As your library grows, you may want a dedicated documentation website with better organization, search functionality, and examples. You can specify your documentation site URL in the `manifest.daxlib` file:
There are many options for hosting documentation websites. A popular choice is [GitHub Pages](https://docs.github.com/en/pages), which is:
26
+
27
+
-**Free** for public repositories
28
+
-**Integrated** with GitHub repositories
29
+
-**Automatic** - deploys from your repo
30
+
-**Custom domains** - supports your own domain name
31
+
32
+
GitHub Pages hosts static websites (HTML, CSS, and JavaScript files) directly from your repository.
33
+
34
+
## Static Site Generators (SSG)
35
+
36
+
While you can manually create HTML files, **Static Site Generators (SSG)** make documentation much easier. SSGs convert markdown files and templates into a complete website at build time.
37
+
38
+
**Benefits:**
39
+
- Write content in simple markdown (`.md` files)
40
+
- Use themes for professional-looking sites
41
+
- Built-in features like search, navigation, and versioning
42
+
- No database or server required
43
+
44
+
### Popular SSG Options
45
+
46
+
| SSG | Language | Why Choose It |
47
+
|-----|----------|---------------|
48
+
|**Jekyll**| Ruby |**Native GitHub Pages support** - zero configuration deployment. Officially supported by GitHub Pages. |
49
+
|**Hugo**| Go |**Extremely fast builds** - ideal for large documentation sites with hundreds of pages. |
50
+
|**MkDocs**| Python |**Documentation-focused** - simple configuration, designed specifically for docs. Works great with the Material theme. |
51
+
|**Docusaurus**| React |**Feature-rich** - built by Meta for open-source docs. Includes versioning, search, and i18n out of the box. |
52
+
53
+
> **GitHub Pages & Jekyll:** GitHub Pages has built-in Jekyll support. When you push to your repository, GitHub automatically runs `jekyll build` and deploys your site. Other SSGs require a [GitHub Actions workflow](https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site#publishing-with-a-custom-github-actions-workflow) to build the site before deployment.
54
+
55
+
## Example: daxlib.svg Documentation
56
+
57
+
The `daxlib.svg` library uses **Material for MkDocs** to generate its documentation site.
For a step-by-step guide on building a similar site, see this [blog post](https://evaluationcontext.github.io/posts/DaxLibContribute/#adding-a-docs-site).
1.**Choose an SSG** based on your familiarity with the language and needs
68
+
2.**Follow the SSG's documentation** to set up your project structure
69
+
3.**Write your documentation** in markdown files
70
+
4.**Configure GitHub Pages** in your repository settings
71
+
5.**Add the site URL** to your `manifest.daxlib` under `projectUrl`
72
+
73
+
> For Medium/Large libraries, you can keep your documentation in the same repository as your library code, or create a separate `docs-yourLibrary` repository.
This creates a personal copy of the repository in your GitHub account.
20
+
This creates a personal copy of the repository in your GitHub account.
21
+
22
+
> Do not make changes directly on the `main` branch. Always create a separate branch for each change you want to make. For example, `add-my-package-version-1.0.0`. This keeps your work isolated until it's reviewed and approved.
23
+
24
+
## Create a folder
25
+
26
+
Create a folder for your package in `/packages/`, following the [naming conventions](naming-conventions.md) for both the folder structure and library name. For a library named `Contoso.Conversion` with version `1.0.0`, the folder structure should be `/packages/c/contoso.conversion/1.0.0/`
17
27
18
-
**Remarks**:
28
+
## Create the package
19
29
20
-
Do not make changes directly on the `main` branch. Always create a separate branch for each change you want to make. For example, `add-my-package-version-1.0.0`. This keeps your work isolated until it's reviewed and approved.
30
+
DAX lib expects a `manifest.daxlib` and `lib/functions.tmdl` files. A `README.md` and `icon.png` can be optionally included.
21
31
22
-
2.**Create a folder** for your package in `/packages/` and follow the [naming conventions](naming-conventions.md) for both the folder structure and name.
You can optionally use the [DaxLib.Sample](https://github.com/daxlib/daxlib/tree/main/packages/d/daxlib.sample/0.1.6) package as a starting point: copy it, rename it according to your library’s name, and then update its contents to match your library.
48
+
> You can use the [DaxLib.Sample](https://github.com/daxlib/daxlib/tree/main/packages/d/daxlib.sample/0.1.6) package as a starting point: copy it, rename it according to your library's name, and then update its contents to match your library.
25
49
26
-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the folder structure should be:
50
+
### manifest.daxlib
27
51
28
-
```bash
29
-
/packages/c/contoso.conversion/1.0.0/
30
-
```
31
-
32
-
3. **Create the manifest**in`manifest.daxlib` file.
33
-
34
-
The `manifest.daxlib` is a mandatory file contains the package properties in JSON format. You can see the [DaxLib.Sample](https://daxlib.org/package/DaxLib.Sample/#code) package for an example and refer to the [JSON schema](https://github.com/daxlib/daxlib/blob/main/schemas/manifest/1.0.0/manifest.1.0.0.schema.json) for the complete specification of available properties.
52
+
*Required:* The package properties in JSON format.
35
53
36
-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the manifest file should be located at:
Refer to the [JSON schema](https://github.com/daxlib/daxlib/blob/main/schemas/manifest/1.0.0/manifest.1.0.0.schema.json) for the complete specification of available properties. You can also refer to the example [DaxLib.Sample](https://daxlib.org/package/DaxLib.Sample/#code) package.
41
71
42
-
4. **Create the DAX user-defined functions**in`lib/functions.tmdl` and follow the [naming conventions](naming-conventions.md) for the functionnames.
72
+
### lib/functions.tmdl
43
73
44
-
The file `lib/functions.tmdl` is a mandatory file and contains the source code of the DAX user-defined functions using the TMDL syntax. For an example, see the [DaxLib.Sample](https://daxlib.org/package/DaxLib.Sample/#code) package.
45
-
46
-
**Remarks**:
47
-
- The `functions.tmdl` file should contain only the functiondefinitions without the `createOrReplace` command.
48
-
- Optional: add comments describing the functionand its parameters to improve readability and usability, as suggested in the [DAX naming convention](https://docs.sqlbi.com/dax-style/dax-naming-conventions#comments).
49
-
- Each UDF must include the mandatory annotations: `DAXLIB_PackageId` and `DAXLIB_PackageVersion`.
74
+
*Required:* Contains TMDL definition of the functions within your library. TMDL script must *not* have `CreateOrReplace` keyword.
50
75
51
-
Example: for a library named `Contoso.Conversion` with version `1.0.0` the annotations should be:
52
-
53
-
``` text
54
-
annotation DAXLIB_PackageId = Contoso.Conversion
55
-
annotation DAXLIB_PackageVersion = 1.0.0
56
-
```
76
+
```dax
77
+
/// Convert from Celsius(°C) to Fahrenheit(°F)
78
+
/// @param {decimal} temperature – The temperature in Celsius
79
+
/// @returns The temperature converted to Fahrenheit
80
+
FUNCTION CelsiusToFahrenheit = ( temperature: DOUBLE ) =>
81
+
( temperature * ( 9 / 5 ) ) + 32
57
82
58
-
5. **(Optional) Add a custom icon for your library**
83
+
annotation DAXLIB_PackageId = Contoso.Conversion
84
+
annotation DAXLIB_PackageVersion = 0.1.0
85
+
...
86
+
```
59
87
60
-
You can include a custom icon for your library by adding a PNG file inside the library's folder.
61
-
62
-
**Remarks**:
63
-
- The icon file must be in PNG format (`.PNG`), with a maximum size of 100 KB.
88
+
#### Naming Convention
64
89
65
-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the icon file at:
90
+
There are some guidelines on DAX UDF naming conventions:
You can include a README file to provide documentation for your library. It can include general information about the library, usage instructions, examples, and any notes for users.
83
-
84
-
**Remarks**:
85
-
- The file must be in Markdown format (`.MD`), with a maximum size of 100 KB.
86
-
- For security reasons, only a limited set of Markdown features are supported, and external links may be restricted to trusted domains.
104
+
### icon.png
105
+
106
+
*Optional:* icon for library
87
107
88
-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the README file at:
108
+
The icon file must be in PNG format (.PNG), with a maximum size of 100 KB.
89
109
90
-
```bash
91
-
/packages/c/contoso.conversion/1.0.0/README.md
92
-
```
110
+
### README.md
111
+
112
+
*Optional:* Markdown docs file, with general information about the library, usage instructions, examples, and any notes for users
93
113
94
-
If you include a README file, you must also update the `manifest.daxlib` to specify the file path.
114
+
The file must be in Markdown format (.MD), with a maximum size of 100 KB. For security reasons, only a limited set of Markdown features are supported, and external links may be restricted to trusted domains.
95
115
96
-
```json
97
-
{
98
-
// ...other manifest properties...
99
-
"readme": "/README.md"
100
-
}
101
-
```
116
+
## Submitting Library to DAX Lib
102
117
103
-
7. **Create a pull request** to publish the library on [daxlib.org](https://daxlib.org/)
118
+
Create a pull request from your fork (`<youraccount>/daxlib`) to `daxlib/daxlib` to publish the library on [daxlib.org](https://daxlib.org/). The pull request must be approved manually by DAX Lib owners/maintainers. After approval your library will appear on [DAX Lib](https://daxlib.org/) for other to download and use
104
119
105
-
- Go [here](https://github.com/daxlib/daxlib/pull/new) to create a new pull request from your forked repository to the official DAX Lib repository.
106
-
- The pull request must be approved manually by DAX Lib owners/maintainers.
107
-
- When the pull request is approved, the package is immediately published.
120
+
> **Packages are immutable**
121
+
>
122
+
> After a pull request has been accepted, Packages are immutable. If you want to submit any changes to functions or files, a new version (i.e. v0.1.0 à v0.2.0 ) must be created, and function annotations and `manifest.daxlib` must be updated with the new version number. Changes can then be submitted with a new pull request.
0 commit comments