Skip to content

Make inline code blocks stand out more #398

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

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open

Make inline code blocks stand out more #398

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e7cb84
Better highlighting of code & values in descriptions
Matthbo Apr 23, 2025
3f67e0d
Replace surround literal values with code blocks instead of backticks
Matthbo Apr 23, 2025
45938f3
Use `<pre></pre>` instead & fix tests
Matthbo Apr 24, 2025
bf7514e
Update styles to work better with inline pre elements
Matthbo Apr 24, 2025
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
8 changes: 2 additions & 6 deletions frank-doc-doclet/src/main/java/org/frankframework/frankdoc/Utils.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,6 @@
import org.frankframework.frankdoc.model.EnumValue;
import org.frankframework.frankdoc.util.LogUtil;
import org.frankframework.frankdoc.wrapper.FrankClass;
import org.frankframework.frankdoc.wrapper.FrankDocException;
import org.frankframework.frankdoc.wrapper.FrankMethod;
import org.frankframework.frankdoc.wrapper.FrankType;
import org.xml.sax.ContentHandler;
Expand All @@ -45,9 +44,7 @@
import javax.xml.XMLConstants;
import javax.xml.parsers.ParserConfigurationException;
import javax.xml.parsers.SAXParserFactory;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.Reader;
import java.io.StringReader;
Expand All @@ -64,7 +61,6 @@
import java.util.function.Function;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;

/**
* Utility methods for the Frank!Doc.
Expand Down Expand Up @@ -384,8 +380,8 @@ private static String getCodeValueReplacement(String codeBlock) {
return "<code>" + StringEscapeUtils.escapeHtml4(codeBlock) + "</code>";
}

private static String getLiteralValueReplacement(String value) {
return String.format("`%s`", StringEscapeUtils.escapeHtml4(value));
private static String getLiteralValueReplacement(String codeBlock) {
return "<pre>" + StringEscapeUtils.escapeHtml4(codeBlock) + "</pre>";
}

private static String getClassFieldValueReplacement(String ref, FrankClass context) {
Expand Down
8 changes: 4 additions & 4 deletions frank-doc-doclet/src/test/resources/doc/examplesExpected/documented.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -103,7 +103,7 @@
"parameters": [
{
"name": "stubFilename",
"description": "will <u>not</u> be handed to the sender\n and it is used at runtime instead of the `stubFilename` specified by the attribute. A lookup of the\n file for this stubFilename will be done at runtime, while the file for the stubFilename specified\n as an attribute will be done at configuration time."
"description": "will <u>not</u> be handed to the sender\n and it is used at runtime instead of the <pre>stubFilename</pre> specified by the attribute. A lookup of the\n file for this stubFilename will be done at runtime, while the file for the stubFilename specified\n as an attribute will be done at configuration time."
}
],
"forwards": [
Expand All @@ -117,11 +117,11 @@
"name": "presumedTimeout"
},
{
"name": "`interrupt`"
"name": "<pre>interrupt</pre>"
},
{
"name": "&lt;defined-by-sender&gt;",
"description": "any `forward`, as returned by name by {@link ISender sender}"
"description": "any <pre>forward</pre>, as returned by name by {@link ISender sender}"
}
]
},
Expand Down Expand Up @@ -163,4 +163,4 @@
]
}
]
}
}
4 changes: 2 additions & 2 deletions frank-doc-doclet/src/test/resources/doc/examplesExpected/simple.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -149,7 +149,7 @@
"org.frankframework.frankdoc.testtarget.examples.simple.Start": {
"name": "Start",
"fullName": "org.frankframework.frankdoc.testtarget.examples.simple.Start",
"description": "Description of Start. Value of VARIABLE is <code>variable value</code>. Value of TheEnum.ENUM_CONSTANT is <code>enum constant</code>.\n Value of literal is `This is a literal`.",
"description": "Description of Start. Value of VARIABLE is <code>variable value</code>. Value of TheEnum.ENUM_CONSTANT is <code>enum constant</code>.\n Value of literal is <pre>This is a literal</pre>.",
"parent": "org.frankframework.frankdoc.testtarget.examples.simple.AbstractParentOfStart",
"elementNames": [
{
Expand Down Expand Up @@ -252,4 +252,4 @@
]
}
]
}
}
2 changes: 1 addition & 1 deletion frank-doc-doclet/src/test/resources/doc/examplesExpected/simple.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
<xs:element name="Start">
<xs:annotation>
<xs:documentation>Description of Start. Value of VARIABLE is &lt;code&gt;variable value&lt;/code&gt;. Value of TheEnum.ENUM_CONSTANT is &lt;code&gt;enum constant&lt;/code&gt;.
Value of literal is `This is a literal`.</xs:documentation>
Value of literal is &lt;pre&gt;This is a literal&lt;/pre&gt;.</xs:documentation>
</xs:annotation>
<xs:complexType>
<xs:complexContent>
Expand Down
7 changes: 7 additions & 0 deletions frank-doc-frontend/src/app/views/details/details-element/details-element.component.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,13 +90,20 @@ h3 {

.syntax > pre {
position: relative;
display: block;
padding: 26px;
border-radius: 8px;
border: 1px solid var(--ff-bgcolor-gray);
font-size: 16px;
color: var(--ff-color-dark);
background: rgba(237, 237, 237, 0.5);

code {
padding: 0;
border: none;
background: transparent;
}

button {
position: absolute;
top: 15px;
Expand Down
42 changes: 27 additions & 15 deletions frank-doc-frontend/src/styles.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
/* You can add global styles to this file, and also import other style files */
@use "sass:meta";
@use "sass:map";

@use '@frankframework/angular-components';
@use '@frankframework/angular-components/styles/variables';

$custom-variables: ('bgcolor-light-gray': #e5e5e5);

@font-face {
font-family: 'DM Mono';
Expand All @@ -22,8 +24,12 @@ app-root {
@each $key, $value in meta.module-variables('variables') {
--#{$key}: #{$value};
}
@each $key, $value in $custom-variables {
--#{$key}: #{$value};
}
}


.page-container {
display: flex;
max-width: 100%;
Expand Down Expand Up @@ -102,21 +108,31 @@ h3.sub-title {
.javadoc,
.details .section {
pre {
padding: 8px;
border-radius: 8px;
border: 1px solid variables.$ff-bgcolor-gray;
color: variables.$ff-color-dark;
background: rgba(237, 237, 237, 0.50);
word-break: break-all;
word-wrap: break-word;
white-space: normal;
overflow: auto;

code {
display: inline-block;

& > code {
display: inline-block;
padding: 8px;
border-radius: 8px;
border: 1px solid variables.$ff-bgcolor-gray;
color: variables.$ff-color-dark;
background: rgba(237, 237, 237, 0.50);
word-break: break-all;
word-wrap: break-word;
overflow: auto;
white-space: pre;
font-size: 100%;
}
}

code {
padding: .2em .4em;
font-family: 'DM Mono', monospace;
font-size: 85%;
background: map.get($custom-variables, 'bgcolor-light-gray');
border-radius: 5px;
}

a {
color: variables.$ff-anchor-default;
font-size: 16px;
Expand All @@ -136,10 +152,6 @@ h3.sub-title {
text-underline-position: from-font;
}
}

code {
font-family: 'DM Mono', monospace;
}
}

.javadoc p,
Expand Down