www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Better ddoc defaults?

reply Yuxuan Shui <yshuiv7 gmail.com> writes:
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?
Mar 09
next sibling parent reply Adam D. Ruppe <destructionator gmail.com> writes:
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 ?
Mar 09
parent reply Yuxuan Shui <yshuiv7 gmail.com> writes:
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

 ?
Mar 09
parent Adam D. Ruppe <destructionator gmail.com> writes:
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.
Mar 09
prev sibling next sibling parent "H. S. Teoh via Digitalmars-d" <digitalmars-d puremagic.com> writes:
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.
Mar 09
prev sibling parent reply Petar Kirov [ZombineDev] <petar.p.kirov gmail.com> writes:
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.
Mar 09
parent reply Yuxuan Shui <yshuiv7 gmail.com> writes:
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?
Mar 11
parent Yuxuan Shui <yshuiv7 gmail.com> writes:
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
Mar 11