Skip to content

Add new default ddoc theme #6173

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
andralex merged 6 commits into from
Oct 11, 2016
Merged

Add new default ddoc theme #6173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
3516ed5
Ddoc: wrap each symbol in the DDOC_MEMBER macro
jacob-carlborg Oct 1, 2016
cab2c33
Ddoc: add new macros: DDOC_MEMBER_HEADER and DDOC_HEADER_ANCHOR
jacob-carlborg Oct 1, 2016
0cbab45
Move built-in ddoc macros to its own file
jacob-carlborg Oct 2, 2016
fa8c8f2
Add new default ddoc theme
jacob-carlborg Oct 3, 2016
8ed9640
Strip leading newlines for unit tests rendered as ddoc examples
jacob-carlborg Oct 9, 2016
9329325
Update ddoc tests
jacob-carlborg Oct 9, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
735 changes: 735 additions & 0 deletions res/default_ddoc_theme.ddoc
View file
Open in desktop

Large diffs are not rendered by default.

204 changes: 66 additions & 138 deletions src/doc.d
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -349,120 +349,7 @@ extern (C++) static TemplateDeclaration getEponymousParent(Dsymbol s)
return (td && getEponymousMember(td)) ? td : null;
}

extern (C++) __gshared const(char)* ddoc_default = "DDOC = <html><head>
$(DDOC_COMMENT Generated by Ddoc from $(SRCFILENAME))
<META http-equiv=\"content-type\" content=\"text/html; charset=utf-8\">
<title>$(TITLE)</title>
</head><body>
<h1>$(TITLE)</h1>
$(BODY)
<hr>$(SMALL Page generated by $(LINK2 http://dlang.org/ddoc.html, Ddoc). $(COPYRIGHT))
</body></html>

B = <b>$0</b>
I = <i>$0</i>
U = <u>$0</u>
P = <p>$0</p>
DL = <dl>$0</dl>
DT = <dt>$0</dt>
DD = <dd>$0</dd>
TABLE = <table>$0</table>
TR = <tr>$0</tr>
TH = <th>$0</th>
TD = <td>$0</td>
OL = <ol>$0</ol>
UL = <ul>$0</ul>
LI = <li>$0</li>
BIG = <big>$0</big>
SMALL = <small>$0</small>
BR = <br>
LINK = <a href=\"$0\">$0</a>
LINK2 = <a href=\"$1\">$+</a>
LPAREN= (
RPAREN= )
BACKTICK= `
DOLLAR= $
DEPRECATED= $0

RED = <font color=red>$0</font>
BLUE = <font color=blue>$0</font>
GREEN = <font color=green>$0</font>
YELLOW =<font color=yellow>$0</font>
BLACK = <font color=black>$0</font>
WHITE = <font color=white>$0</font>

D_CODE = <pre class=\"d_code\">$0</pre>
DDOC_BACKQUOTED = $(D_INLINECODE $0)
D_INLINECODE = <pre style=\"display:inline;\" class=\"d_inline_code\">$0</pre>
D_COMMENT = $(GREEN $0)
D_STRING = $(RED $0)
D_KEYWORD = $(BLUE $0)
D_PSYMBOL = $(U $0)
D_PARAM = $(I $0)

DDOC_COMMENT = <!-- $0 -->
DDOC_DECL = $(DT $(BIG $0))
DDOC_DECL_DD = $(DD $0)
DDOC_DITTO = $(BR)$0
DDOC_SECTIONS = $0
DDOC_SUMMARY = $0$(BR)$(BR)
DDOC_DESCRIPTION = $0$(BR)$(BR)
DDOC_AUTHORS = $(B Authors:)$(BR)
$0$(BR)$(BR)
DDOC_BUGS = $(RED BUGS:)$(BR)
$0$(BR)$(BR)
DDOC_COPYRIGHT = $(B Copyright:)$(BR)
$0$(BR)$(BR)
DDOC_DATE = $(B Date:)$(BR)
$0$(BR)$(BR)
DDOC_DEPRECATED = $(RED Deprecated:)$(BR)
$0$(BR)$(BR)
DDOC_EXAMPLES = $(B Examples:)$(BR)
$0$(BR)$(BR)
DDOC_HISTORY = $(B History:)$(BR)
$0$(BR)$(BR)
DDOC_LICENSE = $(B License:)$(BR)
$0$(BR)$(BR)
DDOC_RETURNS = $(B Returns:)$(BR)
$0$(BR)$(BR)
DDOC_SEE_ALSO = $(B See Also:)$(BR)
$0$(BR)$(BR)
DDOC_STANDARDS = $(B Standards:)$(BR)
$0$(BR)$(BR)
DDOC_THROWS = $(B Throws:)$(BR)
$0$(BR)$(BR)
DDOC_VERSION = $(B Version:)$(BR)
$0$(BR)$(BR)
DDOC_SECTION_H = $(B $0)$(BR)
DDOC_SECTION = $0$(BR)$(BR)
DDOC_MEMBERS = $(DL $0)
DDOC_MODULE_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_CLASS_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_STRUCT_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_ENUM_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_TEMPLATE_MEMBERS = $(DDOC_MEMBERS $0)
DDOC_ENUM_BASETYPE = $0
DDOC_PARAMS = $(B Params:)$(BR)
$(TABLE $0)$(BR)
DDOC_PARAM_ROW = $(TR $0)
DDOC_PARAM_ID = $(TD $0)
DDOC_PARAM_DESC = $(TD $0)
DDOC_BLANKLINE = $(BR)$(BR)

DDOC_ANCHOR = <a name=\"$1\"></a>
DDOC_PSYMBOL = $(U $0)
DDOC_PSUPER_SYMBOL = $(U $0)
DDOC_KEYWORD = $(B $0)
DDOC_PARAM = $(I $0)
DDOC_CONSTRAINT = $(DDOC_CONSTRAINT) if ($0)
DDOC_OVERLOAD_SEPARATOR =
DDOC_TEMPLATE_PARAM_LIST = $0
DDOC_TEMPLATE_PARAM = $0

ESCAPES = /</&lt;/
/>/&gt;/
/&/&amp;/
";
extern (C++) __gshared const(char)* ddoc_default = import("default_ddoc_theme.ddoc");
extern (C++) __gshared const(char)* ddoc_decl_s = "$(DDOC_DECL ";
extern (C++) __gshared const(char)* ddoc_decl_e = ")\n";
extern (C++) __gshared const(char)* ddoc_decl_dd_s = "$(DDOC_DECL_DD ";
Expand Down Expand Up @@ -752,18 +639,19 @@ extern (C++) static Scope* skipNonQualScopes(Scope* sc)
return sc;
}

extern (C++) static bool emitAnchorName(OutBuffer* buf, Dsymbol s, Scope* sc)
extern (C++) static bool emitAnchorName(OutBuffer* buf, Dsymbol s, Scope* sc, bool includeParent)
{
if (!s || s.isPackage() || s.isModule())
return false;
// Add parent names first
bool dot = false;
if (s.parent)
dot = emitAnchorName(buf, s.parent, sc);
else if (sc)
dot = emitAnchorName(buf, sc.scopesym, skipNonQualScopes(sc.enclosing));
auto eponymousParent = getEponymousParent(s);
if (includeParent && s.parent || eponymousParent)
dot = emitAnchorName(buf, s.parent, sc, includeParent);
else if (includeParent && sc)
dot = emitAnchorName(buf, sc.scopesym, skipNonQualScopes(sc.enclosing), includeParent);
// Eponymous template members can share the parent anchor name
if (getEponymousParent(s))
if (eponymousParent)
return dot;
if (dot)
buf.writeByte('.');
Expand All @@ -782,40 +670,59 @@ extern (C++) static bool emitAnchorName(OutBuffer* buf, Dsymbol s, Scope* sc)
return true;
}

extern (C++) static void emitAnchor(OutBuffer* buf, Dsymbol s, Scope* sc)
extern (C++) static void emitAnchor(OutBuffer* buf, Dsymbol s, Scope* sc, bool forHeader = false)
{
Identifier ident;
{
OutBuffer anc;
emitAnchorName(&anc, s, skipNonQualScopes(sc));
emitAnchorName(&anc, s, skipNonQualScopes(sc), true);
ident = Identifier.idPool(anc.peekSlice());
}

auto pcount = cast(void*)ident in sc.anchorCounts;
typeof(*pcount) count;
if (pcount)
if (!forHeader)
{
// Existing anchor,
// don't write an anchor for matching consecutive ditto symbols
TemplateDeclaration td = getEponymousParent(s);
if (sc.prevAnchor == ident && sc.lastdc && (isDitto(s.comment) || (td && isDitto(td.comment))))
return;
if (pcount)
{
// Existing anchor,
// don't write an anchor for matching consecutive ditto symbols
TemplateDeclaration td = getEponymousParent(s);
if (sc.prevAnchor == ident && sc.lastdc && (isDitto(s.comment) || (td && isDitto(td.comment))))
return;

count = ++*pcount;
}
else
{
sc.anchorCounts[cast(void*)ident] = 1;
count = 1;
count = ++*pcount;
}
else
{
sc.anchorCounts[cast(void*)ident] = 1;
count = 1;
}
}

// cache anchor name
sc.prevAnchor = ident;
buf.writestring("$(DDOC_ANCHOR ");
buf.writestring(ident.toChars());
auto macroName = forHeader ? "DDOC_HEADER_ANCHOR" : "DDOC_ANCHOR";
auto symbolName = ident.toString();
buf.printf("$(%.*s %.*s", cast(int) macroName.length, macroName.ptr,
cast(int) symbolName.length, symbolName.ptr);
// only append count once there's a duplicate
if (count > 1)
buf.printf(".%u", count);

if (forHeader)
{
Identifier shortIdent;
{
OutBuffer anc;
emitAnchorName(&anc, s, skipNonQualScopes(sc), false);
shortIdent = Identifier.idPool(anc.peekSlice());
}

auto shortName = shortIdent.toString();
buf.printf(", %.*s", cast(int) shortName.length, shortName.ptr);
}

buf.writeByte(')');
}

Expand Down Expand Up @@ -962,6 +869,17 @@ extern (C++) void emitComment(Dsymbol s, OutBuffer* buf, Scope* sc)
// Put previous doc comment if exists
if (DocComment* dc = sc.lastdc)
{
assert(dc.a.dim > 0, "Expects at least one declaration for a" ~
"documentation comment");

auto symbol = dc.a[0];
auto symbolName = symbol.ident.toString;

buf.writestring("$(DDOC_MEMBER");
buf.writestring("$(DDOC_MEMBER_HEADER");
emitAnchor(buf, symbol, sc, true);
buf.writeByte(')');

// Put the declaration signatures as the document 'title'
buf.writestring(ddoc_decl_s);
for (size_t i = 0; i < dc.a.dim; i++)
Expand Down Expand Up @@ -995,6 +913,7 @@ extern (C++) void emitComment(Dsymbol s, OutBuffer* buf, Scope* sc)
emitMemberComments(sds, buf, sc);
}
buf.writestring(ddoc_decl_dd_e);
buf.writeByte(')');
//printf("buf.2 = [[%.*s]]\n", buf->offset - o0, buf->data + o0);
}
if (s)
Expand Down Expand Up @@ -1839,11 +1758,12 @@ struct DocComment
buf.writestring(cast(char*)c);
if (utd.codedoc)
{
size_t n = getCodeIndent(utd.codedoc);
auto codedoc = utd.codedoc.stripLeadingNewlines;
size_t n = getCodeIndent(codedoc);
while (n--)
buf.writeByte(' ');
buf.writestring("----\n");
buf.writestring(utd.codedoc);
buf.writestring(codedoc);
buf.writestring("----\n");
highlightText(sc, a, buf, o);
}
Expand Down Expand Up @@ -2817,3 +2737,11 @@ extern (C++) int utfStride(const(char)* p)
utf_decodeChar(p, 4, i, c); // ignore errors, but still consume input
return cast(int)i;
}

inout(char)* stripLeadingNewlines(inout(char)* s)
{
while (s && *s == '\n' || *s == '\r')
s++;

return s;
}
10 changes: 5 additions & 5 deletions src/posix.mak
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -312,7 +312,7 @@ TK_SRC = \
$(TK)/filespec.h $(TK)/mem.h $(TK)/list.h $(TK)/vec.h \
$(TK)/filespec.c $(TK)/mem.c $(TK)/vec.c $(TK)/list.c

STRING_IMPORT_FILES = verstr.h SYSCONFDIR.imp
STRING_IMPORT_FILES = verstr.h SYSCONFDIR.imp ../res/default_ddoc_theme.ddoc

DEPS = $(patsubst %.o,%.deps,$(DMD_OBJS) $(GLUE_OBJS) $(BACK_OBJS))

Expand All @@ -328,14 +328,14 @@ backend.a: $(BACK_OBJS)
$(AR) rcs backend.a $(BACK_OBJS)

dmd_frontend: $(FRONT_SRCS) gluelayer.d $(ROOT_SRCS) newdelete.o $(STRING_IMPORT_FILES) $(HOST_DMD_PATH)
CC=$(HOST_CXX) $(HOST_DMD_RUN) -of$@ $(MODEL_FLAG) -vtls -J. -L-lstdc++ $(DFLAGS) $(filter-out $(STRING_IMPORT_FILES) $(HOST_DMD_PATH),$^) -version=NoBackend
CC=$(HOST_CXX) $(HOST_DMD_RUN) -of$@ $(MODEL_FLAG) -vtls -J. -J../res -L-lstdc++ $(DFLAGS) $(filter-out $(STRING_IMPORT_FILES) $(HOST_DMD_PATH),$^) -version=NoBackend

ifdef ENABLE_LTO
dmd: $(DMD_SRCS) $(ROOT_SRCS) newdelete.o $(GLUE_OBJS) $(BACK_OBJS) $(STRING_IMPORT_FILES) $(HOST_DMD_PATH)
CC=$(HOST_CXX) $(HOST_DMD_RUN) -of$@ $(MODEL_FLAG) -vtls -J. -L-lstdc++ $(DFLAGS) $(filter-out $(STRING_IMPORT_FILES) $(HOST_DMD_PATH),$^)
CC=$(HOST_CXX) $(HOST_DMD_RUN) -of$@ $(MODEL_FLAG) -vtls -J. -J../res -L-lstdc++ $(DFLAGS) $(filter-out $(STRING_IMPORT_FILES) $(HOST_DMD_PATH),$^)
else
dmd: $(DMD_SRCS) $(ROOT_SRCS) newdelete.o glue.a backend.a $(STRING_IMPORT_FILES) $(HOST_DMD_PATH)
CC=$(HOST_CXX) $(HOST_DMD_RUN) -of$@ $(MODEL_FLAG) -vtls -J. -L-lstdc++ $(DFLAGS) $(filter-out $(STRING_IMPORT_FILES) $(HOST_DMD_PATH),$^)
CC=$(HOST_CXX) $(HOST_DMD_RUN) -of$@ $(MODEL_FLAG) -vtls -J. -J../res -L-lstdc++ $(DFLAGS) $(filter-out $(STRING_IMPORT_FILES) $(HOST_DMD_PATH),$^)
endif

clean:
Expand Down Expand Up @@ -493,7 +493,7 @@ zip:
ifneq ($(DOCDIR),)
html: $(DOCDIR)/.generated
$(DOCDIR)/.generated: $(DMD_SRCS) $(ROOT_SRCS) $(HOST_DMD_PATH) project.ddoc
$(HOST_DMD_RUN) -of- $(MODEL_FLAG) -J. -c -Dd$(DOCDIR)\
$(HOST_DMD_RUN) -of- $(MODEL_FLAG) -J. -J../res -c -Dd$(DOCDIR)\
$(DFLAGS) project.ddoc $(DOCFMT) $(DMD_SRCS) $(ROOT_SRCS)
touch $@
endif
Expand Down
10 changes: 6 additions & 4 deletions src/win32.mak
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,8 @@ BACK_HDRS=$C/bcomplex.d $C/cc.d $C/cdef.d $C/cgcv.d $C/code.d $C/cv4.d $C/dt.d $

TK_HDRS= $(TK)/dlist.d

STRING_IMPORT_FILES= verstr.h ../res/default_ddoc_theme.ddoc

DMD_SRCS=$(FRONT_SRCS) $(GLUE_SRCS) $(BACK_HDRS) $(TK_HDRS)

# Glue layer
Expand Down Expand Up @@ -293,11 +295,11 @@ backend.lib : $(BACKOBJ) $(OBJ_MSVC)

LIBS= glue.lib backend.lib

dmd_frontend.exe: $(FRONT_SRCS) gluelayer.d $(ROOT_SRCS) newdelete.obj verstr.h
$(HOST_DC) $(DSRC) -of$@ -vtls -J. -L/STACK:8388608 $(DFLAGS) $(FRONT_SRCS) gluelayer.d $(ROOT_SRCS) newdelete.obj -version=NoBackend
dmd_frontend.exe: $(FRONT_SRCS) gluelayer.d $(ROOT_SRCS) newdelete.obj $(STRING_IMPORT_FILES)
$(HOST_DC) $(DSRC) -of$@ -vtls -J. -J../res -L/STACK:8388608 $(DFLAGS) $(FRONT_SRCS) gluelayer.d $(ROOT_SRCS) newdelete.obj -version=NoBackend

$(TARGETEXE): $(DMD_SRCS) $(ROOT_SRCS) newdelete.obj $(LIBS) verstr.h
$(HOST_DC) $(DSRC) -of$@ -vtls -J. -L/STACK:8388608 $(DFLAGS) $(DMD_SRCS) $(ROOT_SRCS) newdelete.obj $(LIBS)
$(TARGETEXE): $(DMD_SRCS) $(ROOT_SRCS) newdelete.obj $(LIBS) $(STRING_IMPORT_FILES)
$(HOST_DC) $(DSRC) -of$@ -vtls -J. -J../res -L/STACK:8388608 $(DFLAGS) $(DMD_SRCS) $(ROOT_SRCS) newdelete.obj $(LIBS)

############################ Maintenance Targets #############################

Expand Down
Loading