I'm using ddoc for the first time. I was naively expecting something resembles dlang.org, and the results is a bit disappointing. So I looked at dlang.org and realized lots and lots of ddoc templates are required to achieve that.

As the developer of a tiny package that nobody cares, I want to have a nice looking documents page, but I don't want put too much (or any!) time into it. And I don't care whether my documents have any "personality". I guess a lot people would agree.

So why don't we make the defaults more beautiful? Or make the dlang.org templates easier to adopt for average users?

On Thursday, 9 March 2017 at 21:08:17 UTC, Yuxuan Shui wrote:
> So why don't we make the defaults more beautiful?

ddoc DID just recently get an overhaul... do your pages look like

http://arsdnet.net/dcode/simpledisplay.html

or like this

http://arsdnet.net/ddoc/simpledisplay.html

?

On Thu, Mar 09, 2017 at 09:08:17PM +0000, Yuxuan Shui via Digitalmars-d wrote:
> I'm using ddoc for the first time. I was naively expecting something resembles dlang.org, and the results is a bit disappointing. So I looked at dlang.org and realized lots and lots of ddoc templates are required to achieve that.
> 
> As the developer of a tiny package that nobody cares, I want to have a nice looking documents page, but I don't want put too much (or any!) time into it. And I don't care whether my documents have any "personality". I guess a lot people would agree.

If you're interested, I wrote a simple set of drop-in replacement macros that gives you a decent formatting without getting to the fanciness (and complexity) of dlang.org docs:

	https://github.com/quickfur/Viola-ddoc-macros


> So why don't we make the defaults more beautiful? Or make the dlang.org templates easier to adopt for average users?

If you feel strongly enough about it, you *could* turn my macros file into a PR and see how it goes? ;-)


T

-- 
Some days you win; most days you lose.

On Thursday, 9 March 2017 at 21:17:11 UTC, Adam D. Ruppe wrote:
> On Thursday, 9 March 2017 at 21:08:17 UTC, Yuxuan Shui wrote:
>> So why don't we make the defaults more beautiful?
>
> ddoc DID just recently get an overhaul... do your pages look like
>
> http://arsdnet.net/dcode/simpledisplay.html

Yes, this one is better, but I'm still not satisfied...

Also this page looks kind of broken?

>
> or like this
>
> http://arsdnet.net/ddoc/simpledisplay.html
>
> ?

On Thursday, 9 March 2017 at 21:43:00 UTC, Yuxuan Shui wrote:
> Also this page looks kind of broken?

The text is unreadably small in places, not sure why. I just ran my file through dmd -D with the newest version, so I assume it is the new default macros.

I don't use ddoc for myself though, I just keep those two files around for comparison.

On Thursday, 9 March 2017 at 21:08:17 UTC, Yuxuan Shui wrote:
> I'm using ddoc for the first time. I was naively expecting something resembles dlang.org, and the results is a bit disappointing. So I looked at dlang.org and realized lots and lots of ddoc templates are required to achieve that.
>
> As the developer of a tiny package that nobody cares, I want to have a nice looking documents page, but I don't want put too much (or any!) time into it. And I don't care whether my documents have any "personality". I guess a lot people would agree.
>
> So why don't we make the defaults more beautiful? Or make the dlang.org templates easier to adopt for average users?

My favorite one is: https://github.com/MartinNowak/scod.

BTW, the default ddox (the one that comes with dub) is getting an upgrade soon: https://github.com/rejectedsoftware/ddox/pull/149
https://github.com/rejectedsoftware/ddox/pull/150.

On Friday, 10 March 2017 at 07:58:36 UTC, Petar Kirov [ZombineDev] wrote:
> On Thursday, 9 March 2017 at 21:08:17 UTC, Yuxuan Shui wrote:
>> I'm using ddoc for the first time. I was naively expecting something resembles dlang.org, and the results is a bit disappointing. So I looked at dlang.org and realized lots and lots of ddoc templates are required to achieve that.
>>
>> As the developer of a tiny package that nobody cares, I want to have a nice looking documents page, but I don't want put too much (or any!) time into it. And I don't care whether my documents have any "personality". I guess a lot people would agree.
>>
>> So why don't we make the defaults more beautiful? Or make the dlang.org templates easier to adopt for average users?
>
> My favorite one is: https://github.com/MartinNowak/scod.
>
> BTW, the default ddox (the one that comes with dub) is getting an upgrade soon: https://github.com/rejectedsoftware/ddox/pull/149
> https://github.com/rejectedsoftware/ddox/pull/150.

I tried ddox, and it worked pretty well. Only problem is that, ddox uses the json output of dmd, which is different from dmd -D result. dmd -D will include the then-branch of static-ifs and version blocks that's been compiled in, but the json output doesn't.

Is this by design? Or can we make the json output consistent with the ddoc output?

On Saturday, 11 March 2017 at 09:54:25 UTC, Yuxuan Shui wrote:
> On Friday, 10 March 2017 at 07:58:36 UTC, Petar Kirov [ZombineDev] wrote:
>> On Thursday, 9 March 2017 at 21:08:17 UTC, Yuxuan Shui wrote:
>>> [...]
>>
>> My favorite one is: https://github.com/MartinNowak/scod.
>>
>> BTW, the default ddox (the one that comes with dub) is getting an upgrade soon: https://github.com/rejectedsoftware/ddox/pull/149
>> https://github.com/rejectedsoftware/ddox/pull/150.
>
> I tried ddox, and it worked pretty well. Only problem is that, ddox uses the json output of dmd, which is different from dmd -D result. dmd -D will include the then-branch of static-ifs and version blocks that's been compiled in, but the json output doesn't.
>
> Is this by design? Or can we make the json output consistent with the ddoc output?

I opened a PR for this: https://github.com/dlang/dmd/pull/6621