Conversation
|
Nice work, @jacob-carlborg! Can you post a before and after screenshots for comparison? |
|
Sure. |
|
|
jacob-carlborg
changed the title
This allows better control of formatting of the output. For example, it allows to output an unordered list instead of a description list. By default it expands the first argument ($0) as is, basically making the macro disappear, to keep backwards compatibility.
The second parameter ($1) of the DDOC_HEADER_ANCHOR macro expands to the fully qualified name of the current symbol without the package and module prefix. That is, for a module level symbol it's the name of a symbol. For a nested symbol, like a method in a class, it's the symbol name prefixed with the class name. The third parameter ($2) expands to just the name of the current symbol. The DDOC_MEMBER_HEADER wraps DDOC_HEADER_ANCHOR to allow a sensible output format. The DDOC_MEMBER_HEADER is wrapped in the DDOC_MEMBER macro. By default these two macros expand to nothing, to keep backwards compatibility.
This adds a new default ddoc theme that generates a result with a design that can be used as is without manual styling. It outputs modern HTML 5, CSS 3 and passes the W3 HTML validator. This makes the out of the box experience a lot more pleasant.
jacob-carlborg
force-pushed
the
ddoc-new-theme
branch
from
7685e40 to
9329325
Compare
jacob-carlborg
changed the title
|
@andralex ping |
|
Very nice. Thanks! |
|
That was quick, thanks 😃. |
|
This introduced some regressions in dlang.org (look at the doc autotester diffs for details). Because we auto-deploy website changes, the regressions have already propagated to the live website: http://dlang.org/phobos-prerelease/std_datetime.html#Month Also, this made a massive impact on DDoc tests: test files that were previously under 100 lines are now over 1000 lines long. Perhaps there should be a way to opt-out of the new stylesheet, or the tests should be built with a simple .ddoc file that mimics the old default style. Unless @jacob-carlborg can provide a timely dlang.org fix, I suggest that this is immediately reverted. @andralex |
|
If we preserve the existing ecosystem 100% by definition we cannot make progress. I'm okay with reverting the PR for now until we sort out the problems, but I'd rather put up with the larger test files rather than use a smaller mockup. What are the issues caused by the longer test files? |
Yes, but breaking the live site could've been avoided by checking the CI systems in place to prevent exactly this. (Unfortunately there is no automated way that I know of to test if something "looks broken", so DDoc-related changes should be evaluated by at least a cursory examination of the diffs, available only two clicks away.)
What I'm trying to say is that I think it would be better if the problems were noticed and sorted out before merging. :)
That part was more of an observation in case it's a concern to someone, however one issue is that DDoc regressions (which the test files are supposed to help identify) will be more difficult to identify when the diffs are so big, that they are difficult to make sense of. |
@CyberShadow working on it. It should be easy to fix, it's one or two new macros that needs proper configuration.
I suggested having DMD output a separate CSS file, but Andrei wanted a simper solution. |
The new Ddoc theme [1] introduced three new macros: DDOC_MEMBER, DDOC_MEMBER_HEADER and DDOC_HEADER_ANCHOR. This tweak configures these new macros to have no impact on the existing ddoc themes. [1] dlang/dmd#6173
dlang#6173 removed the ```__YEAR__``` tag from dlang#1699
You can render and visually diff, but that's rather |
5 participants
This adds a new default ddoc theme that generates a result with a design that can be used as is without manual styling. It outputs modern HTML 5, CSS 3 and passes the W3 HTML validator. This makes the out of the box experience a lot more pleasant.
The two first commits are from #6170.
Depends on #6170.