www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.announce - New WIP DUB documentation

reply WebFreak001 <d.forum webfreak.org> writes:
Hi all, I'm currently working on new revamped DUB documentation, 
check it out if you want, it currently contains most old 
documentation plus a big bunch of new documentation:

https://docs.webfreak.org/

Repository: https://github.com/WebFreak001/dub-docs-v2

Instead of being based on diet templates and needing to be 
compiled using `dmd` and build all of vibe.d, it now uses 
[mkdocs](https://www.mkdocs.org/) with a customized [mkdocs 
material theme](https://squidfunk.github.io/mkdocs-material/), so 
now the documentation is Markdown based, which should be more 
familiar to a lot of people + it has a great offline search index 
and a bunch of interactive elements, that also work without JS.

The dub.json and dub.sdl documentation is now merged on the same 
page, where you can simply swap between them whenever you like. 
If you have JS enabled it will also sync it across the entire 
page and persist across page loads.

Writing the docs is really quite easy, you can have it locally be 
served by first installing the dependencies using

```
pip install -r requirements.txt
```

and then when working on it running

```
mkdocs serve
```

to have auto-updating docs in the browser. (auto refresh whenever 
you change anything)

So if you find any typos or want to complete the docs, feel free 
to open a PR on https://github.com/WebFreak001/dub-docs-v2

I plan to have easily discoverable edit links linked on the page 
soon too, which should theoretically just be a simple mkdocs 
configuration thing that's probably already implemented.

Someone from the community has already contributed a dark theme 
to it. :)

[![new dub documentation preview 
screenshot](https://wfr.moe/f6fgF7.png)](https://docs.webfreak.org)
Aug 15 2022
next sibling parent rikki cattermole <rikki cattermole.co.nz> writes:
It is pretty awesome, a lot easier to digest and get into!
Aug 15 2022
prev sibling next sibling parent Anonymouse <zorael gmail.com> writes:
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:

 [...]


I like it!

Can anything be done about the width of the `buildOptions` table 
though? The whole page takes up about about half of my horizontal 
screen real estate, yet the "corresponding GDC flags" column is 
still partially out of view until I scroll right. I'm on a laptop 
so I can do horizontal scrolls by gesture, but I imagine a user 
with only vertical scrolling has to navigate all the way down to 
the bottom of the table to get the horizontal scroll bar to show?

(I don't know how to solve it neatly but I thought I'd mention 
it.)
Aug 15 2022
prev sibling next sibling parent Ruby The Roobster <rubytheroobster yandex.com> writes:
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:

 [SNIP]


I like the idea, making dub easier to learn for those who are 
unfamiliar, but I have a singular request: Could you do a section 
on setting up a copy of dub-registry?
Aug 15 2022
prev sibling next sibling parent reply =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Looking good, having SDL+JSON on the same page is especially nice and 
something I've been wanting to fix for a while. Also definitely a good 
idea to use a static generator now that the documentation is separate.

One question, though - do you generate the CLI documentation from the 
DUB sources, or is that manual work?
Aug 16 2022
parent WebFreak001 <d.forum webfreak.org> writes:
On Tuesday, 16 August 2022 at 08:13:08 UTC, Sönke Ludwig wrote:

 Looking good, having SDL+JSON on the same page is especially 
 nice and something I've been wanting to fix for a while. Also 
 definitely a good idea to use a static generator now that the 
 documentation is separate.

 One question, though - do you generate the CLI documentation 
 from the DUB sources, or is that manual work?


for the CLI documentation I modified the man generator to output 
markdown instead of man formatting, still need to PR that
Aug 16 2022
prev sibling next sibling parent JG <someone somewhere.com> writes:
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:

 Hi all, I'm currently working on new revamped DUB 
 documentation, check it out if you want, it currently contains 
 most old documentation plus a big bunch of new documentation:

 [...]


Looks really great. Thanks for doing this.
Aug 16 2022
prev sibling next sibling parent jmh530 <john.michael.hall gmail.com> writes:
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:

 Hi all, I'm currently working on new revamped DUB 
 documentation, check it out if you want, it currently contains 
 most old documentation plus a big bunch of new documentation:

 [...]


Looks go to be a big improvement.

Some of the paragraphs on this page are a bit long and might need 
to get broken up.
https://docs.webfreak.org/cli-reference/dub/
Aug 16 2022
prev sibling next sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:

 Hi all, I'm currently working on new revamped DUB 
 documentation, check it out if you want, it currently contains 
 most old documentation plus a big bunch of new documentation:

 https://docs.webfreak.org/


Thank you for doing this!

Not sure if this would be the right place, or if it is addressed 
already, but I repeatedly find myself looking for the right way 
to use a local checkout of a package instead of the dub registry, 
because I keep forgetting. It would be nice to have a section 
like (assuming I got it right):



If your project depends on a package in which you have found a 
problem, or you would like to experiment with changes to it, you 
can force Dub to use a local copy of the package by following 
these steps:

1. Fork the git repository
2. Check out a local clone at `/path/to/the_package`
3. Let Dub know about it:
    `dub add-local /path/to/the_package`
4. Make Dub ignore any configured release tag, so you'll see the 
effect of current changes:
    `dub add-override the_package * /path/to/the_package`

Now you can go ahead and play. Once your PR has been merged and 
released, or you want to revert to upstream, undo your changes by

5. `dub remove-local /path/to/the_package`
6. `dub remove-override the_package *`


-- Bastiaan.
Aug 18 2022
next sibling parent Guillaume Piolat <first.last spam.org> writes:
On Thursday, 18 August 2022 at 10:23:35 UTC, Bastiaan Veelo wrote:



 If your project depends on a package in which you have found a 
 problem, or you would like to experiment with changes to it, 
 you can force Dub to use a local copy of the package by 
 following these steps:

 1. Fork the git repository
 2. Check out a local clone at `/path/to/the_package`
 3. Let Dub know about it:
    `dub add-local /path/to/the_package`
 4. Make Dub ignore any configured release tag, so you'll see 
 the effect of current changes:
    `dub add-override the_package * /path/to/the_package`

 Now you can go ahead and play. Once your PR has been merged and 
 released, or you want to revert to upstream, undo your changes 
 by

 5. `dub remove-local /path/to/the_package`
 6. `dub remove-override the_package *`


 -- Bastiaan.


You can also simply to modify the tree in .dub or %appdata% and 
afterwards copy-paste the change to a git clone. It's more 
dangerous, but I think it's more straighforward too.
Aug 18 2022
prev sibling parent =?UTF-8?Q?S=c3=b6nke_Ludwig?= <sludwig outerproduct.org> writes:
Am 18.08.2022 um 12:23 schrieb Bastiaan Veelo:


 
 If your project depends on a package in which you have found a problem, 
 or you would like to experiment with changes to it, you can force Dub to 
 use a local copy of the package by following these steps:
 
 1. Fork the git repository
 2. Check out a local clone at `/path/to/the_package`
 3. Let Dub know about it:
     `dub add-local /path/to/the_package`
 4. Make Dub ignore any configured release tag, so you'll see the effect 
 of current changes:
     `dub add-override the_package * /path/to/the_package`
 
 Now you can go ahead and play. Once your PR has been merged and 
 released, or you want to revert to upstream, undo your changes by
 
 5. `dub remove-local /path/to/the_package`
 6. `dub remove-override the_package *`


If have a branch checked out whose latest version tag matches the 
version selected by your main project, you can skip the `add-override` 
step, as dub will prefer a repository added with `add-local` over cached 
ones from the registry.

Also, using `add-path` on the parent directory allows you to clone and 
delete repositories at will, without having to use `add-local` and 
`remove-local` each time individually.
Aug 18 2022
prev sibling parent reply Martin Tschierschke <mt smartdolphin.de> writes:
On Monday, 15 August 2022 at 21:32:23 UTC, WebFreak001 wrote:

 Hi all, I'm currently working on new revamped DUB 
 documentation, check it out if you want, it currently contains 
 most old documentation plus a big bunch of new documentation:

 https://docs.webfreak.org/


Looks great!
What about the following idea about **comments for dub.json**: 
Allow the key "comment" inside the json file and alter DUB to 
remove all "comment" key value pairs at the beginning of parsing.
So the file is still valid json but comments are possible like in 
dub.sdl.
```
{
     "comment" : "dub.json can contain comments,too!",
     "name": "myproject",
     "description": "A little web service of mine.",
     "authors": ["Peter Parker", "John Doe"],
     "homepage": "http://myproject.example.com",
     "license": "GPL-2.0",
     "dependencies": {
         "vibe-d": "~>0.9.5"
     }
}
```
Aug 18 2022
next sibling parent reply Bastiaan Veelo <Bastiaan Veelo.net> writes:
On Thursday, 18 August 2022 at 14:00:38 UTC, Martin Tschierschke 
wrote:

 What about the following idea about **comments for dub.json**: 
 Allow the key "comment" inside the json file and alter DUB to 
 remove all "comment" key value pairs at the beginning of 
 parsing.
 So the file is still valid json but comments are possible like 
 in dub.sdl.
 ```
 {
     "comment" : "dub.json can contain comments,too!",
     "name": "myproject",
     "description": "A little web service of mine.",
     "authors": ["Peter Parker", "John Doe"],
     "homepage": "http://myproject.example.com",
     "license": "GPL-2.0",
     "dependencies": {
         "vibe-d": "~>0.9.5"
     }
 }
 ```


That's already possible, as unrecognised items are ignored. This 
is however not flexible enough, as comments are not so much 
wanted for adding explanations but much more for commenting out 
specific parts. It does work sometimes: you can for example 
disable `preBuildCommands` by editing it to 
`preBuildCommandsDISABLED`. I don't think you can comment out a 
dependency this way, and you cannot comment out an item from an 
array like
```json
{
     "preBuildCommands": [
         "step one",

         "step three"
     ]
}
```

-- Bastiaan.
Aug 18 2022
next sibling parent Martin Tschierschke <mt smartdolphin.de> writes:
On Thursday, 18 August 2022 at 20:00:10 UTC, Bastiaan Veelo wrote:

 That's already possible, as unrecognised items are ignored. 
 This is however not flexible enough, as comments are not so 
 much wanted for adding explanations but much more for 
 commenting out specific parts. It does work sometimes: you can 
 for example disable `preBuildCommands` by editing it to 
 `preBuildCommandsDISABLED`. I don't think you can comment out a 
 dependency this way, and you cannot comment out an item from an 
 array like
 ```json
 {
     "preBuildCommands": [
         "step one",

         "step three"
     ]
 }
 ```

 -- Bastiaan.


Ok, thank you, got it.
Aug 24 2022
prev sibling parent Mathias LANG <pro.mathias.lang gmail.com> writes:
On Thursday, 18 August 2022 at 20:00:10 UTC, Bastiaan Veelo wrote:

 That's already possible, as unrecognised items are ignored.


Actually, from next version, dub will start to warn you (in 
dub.json) about unknown keys. It does catch quite a lot of 
mistakes, see 
https://github.com/dlang/dub/pull/2280#issuecomment-1223326664
Aug 24 2022
prev sibling parent reply Andrey Zherikov <andrey.zherikov gmail.com> writes:
Just throwing an idea: may be dub can support yaml which has 
comments?
Aug 24 2022
parent bauss <jacobbauss gmail.com> writes:
On Wednesday, 24 August 2022 at 10:31:55 UTC, Andrey Zherikov 
wrote:

 Just throwing an idea: may be dub can support yaml which has 
 comments?


The sdl format already supports that, which dub uses.

Json is supposed to be deprecated in dub, but obviously works for 
backwards compatibility.

https://sdlang.org/
Aug 24 2022