You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2021/02/22 22:51:26 UTC
[isis] branch ISIS-2444 updated (b6edfb3 -> 989a08f)
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a change to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git.
from b6edfb3 ISIS-2444: fixes xref's for new structure
new 0c82a3a ISIS-2444: fixes references to system overview
new 989a08f ISIS-2444: putative fixes to xref's in system overview
The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
Summary of changes:
.../pages/building-docs-and-website.adoc | 2 +-
.../components/docs/modules/ROOT/pages/about.adoc | 2 +-
.../ROOT/pages/landing-page/components.adoc | 2 +-
.../ROOT/partials/module-nav/components.adoc | 2 +-
core/adoc/modules/ROOT/nav.adoc | 2 -
.../cli/adoc/modules/tooling-cli/pages/about.adoc | 2 +-
.../org/apache/isis/tooling/cli/CliConfig.java | 4 +-
.../cli/adocfix/OrphanedIncludeStatementFixer.java | 18 +++++---
.../isis/tooling/cli/projdoc/ProjectDocModel.java | 53 +++++++++++-----------
.../isis/tooling/cli/projdoc/ProjectDocWriter.java | 4 +-
.../apache/isis/tooling/j2adoc/J2AdocContext.java | 10 ++--
11 files changed, 53 insertions(+), 48 deletions(-)
[isis] 02/02: ISIS-2444: putative fixes to xref's in system overview
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 989a08fd6ae67f7406cd14e1d8e9ac1d44ac28d6
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Feb 22 22:51:12 2021 +0000
ISIS-2444: putative fixes to xref's in system overview
... let's see
---
.../org/apache/isis/tooling/cli/CliConfig.java | 4 +-
.../cli/adocfix/OrphanedIncludeStatementFixer.java | 18 +++++---
.../isis/tooling/cli/projdoc/ProjectDocModel.java | 53 +++++++++++-----------
.../isis/tooling/cli/projdoc/ProjectDocWriter.java | 4 +-
.../apache/isis/tooling/j2adoc/J2AdocContext.java | 10 ++--
5 files changed, 48 insertions(+), 41 deletions(-)
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/CliConfig.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/CliConfig.java
index 08b8d37..1439a48 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/CliConfig.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/CliConfig.java
@@ -92,8 +92,8 @@ public class CliConfig {
@Data
public static class Index {
- private String documentGlobalIndexPath = "pages/index";
- private String documentGlobalIndexXrefPageIdFormat = "system:generated:index/%s.adoc";
+ private String documentGlobalIndexPath = "pages";
+ private String documentGlobalIndexXrefPageIdFormat = "refguide:%s:index/%s.adoc";
private boolean fixOrphanedAdocIncludeStatements = false;
private boolean skipTitleHeader = false;
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/adocfix/OrphanedIncludeStatementFixer.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/adocfix/OrphanedIncludeStatementFixer.java
index 0e77eb4..bcb4f73 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/adocfix/OrphanedIncludeStatementFixer.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/adocfix/OrphanedIncludeStatementFixer.java
@@ -63,9 +63,10 @@ public final class OrphanedIncludeStatementFixer {
val originLines = _Text.readLinesFromFile(adocFile, StandardCharsets.UTF_8);
val lines = IncludeStatements.rewrite(originLines, include->{
- if(include.isLocal()
- || !( "system".equals(include.getComponent()) // TODO should be reasoned from config
- && "generated".equals(include.getModule()))) { // TODO should be reasoned from config
+ final boolean inGlobalIndex =
+ "refguide".equals(include.getComponent()) // TODO should be reasoned from config
+ && include.getNamespace().startsWith(Can.of("index")); // TODO should be reasoned from config
+ if(include.isLocal() || !inGlobalIndex) {
return null; // keep original line, don't mangle
}
@@ -75,14 +76,17 @@ public final class OrphanedIncludeStatementFixer {
j2aContext.findUnitByTypeSimpleName(typeSimpleName)
.ifPresent(unit->{
+ val module = unit.getNamespace().stream()
+ .skip(j2aContext.getNamespacePartsSkipCount())
+ .findFirst().get();
val expected = IncludeStatement.builder()
- .component("system")
- .module("generated")
+ .component("refguide")
+ .module(module)
.type("page")
.namespace(unit.getNamespace().stream()
- .skip(j2aContext.getNamespacePartsSkipCount())
+ .skip(j2aContext.getNamespacePartsSkipCount() + 1) // +1 because is part of the module
.collect(Can.toCan())
- .add(0, "index") //TODO this is antora config specific
+ .add(0, "index") // TODO this is antora config specific
)
.canonicalName(typeSimpleName)
.ext(".adoc")
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java
index 9c61f39..936e20d 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocModel.java
@@ -106,12 +106,9 @@ public class ProjectDocModel {
modules = new TreeSet<ProjectNode>();
projTree.depthFirst(modules::add);
- final SortedSet<File> asciiDocFiles = new TreeSet<>();
val j2aContext = J2AdocContext.builder()
- //.compactFormat()
-// .javaSourceWithFootnotesFormat()
- .formatterFactory(new Function<J2AdocContext, UnitFormatter>() {
+ .formatterFactory(new Function<>() {
@SneakyThrows
@Override
public UnitFormatter apply(J2AdocContext j2AdocContext) {
@@ -127,15 +124,6 @@ public class ProjectDocModel {
.skipTitleHeader(cliConfig.getCommands().getIndex().isSkipTitleHeader())
.build();
- val doc = doc();
- doc.setTitle("System Overview");
-
- _Strings.nonEmpty(cliConfig.getGlobal().getLicenseHeader())
- .ifPresent(notice->AsciiDocFactory.attrNotice(doc, notice));
-
- _Strings.nonEmpty(cliConfig.getCommands().getOverview().getDescription())
- .ifPresent(block(doc)::setSource);
-
// partition modules into sections
val sections = new ArrayList<Section>();
cliConfig.getGlobal().getSections().forEach((section, groupIdArtifactIdPattern)->{
@@ -164,9 +152,20 @@ public class ProjectDocModel {
}
// now generate the overview or index
- writeSections(sections, doc, j2aContext, mode, asciiDocFiles::add);
+ final SortedSet<File> asciiDocFiles = new TreeSet<>();
- ProjectDocWriter.write(cliConfig, doc, j2aContext, mode);
+ val overviewDoc = doc();
+ overviewDoc.setTitle("System Overview");
+
+ _Strings.nonEmpty(cliConfig.getGlobal().getLicenseHeader())
+ .ifPresent(notice->AsciiDocFactory.attrNotice(overviewDoc, notice));
+
+ _Strings.nonEmpty(cliConfig.getCommands().getOverview().getDescription())
+ .ifPresent(block(overviewDoc)::setSource);
+
+ writeSections(sections, overviewDoc, j2aContext, mode, asciiDocFiles::add);
+
+ ProjectDocWriter.write(cliConfig, overviewDoc, j2aContext, mode);
// update include statements ...
OrphanedIncludeStatementFixer.fixIncludeStatements(asciiDocFiles, cliConfig, j2aContext);
@@ -265,7 +264,7 @@ public class ProjectDocModel {
containerView.addAllContainers();
containerView.enableAutomaticLayout(RankDirection.LeftRight);
-
+
val plantUmlSource = c4.toPlantUML(containerView);
return plantUmlSource;
}
@@ -296,19 +295,19 @@ public class ProjectDocModel {
private void writeSections(
final @NonNull List<Section> sections,
- final @NonNull Document doc,
+ final @NonNull Document overviewDoc,
final @NonNull J2AdocContext j2aContext,
final @NonNull Mode mode,
final @NonNull Consumer<File> onAdocFile) {
sections.forEach(section -> {
- writeSection(section, doc, j2aContext, mode, onAdocFile);
+ writeSection(section, overviewDoc, j2aContext, mode, onAdocFile);
});
}
private void writeSection(
final @NonNull Section section,
- final @NonNull Document doc,
+ final @NonNull Document overviewDoc,
final @NonNull J2AdocContext j2aContext,
final @NonNull Mode mode,
final @NonNull Consumer<File> onAdocFile) {
@@ -316,7 +315,7 @@ public class ProjectDocModel {
val sectionName = section.getSectionName();
val groupIdPattern = section.getGroupIdArtifactIdPattern();
- val titleBlock = block(doc);
+ val titleBlock = block(overviewDoc);
val headingLevel =
(groupIdPattern == null || !groupIdPattern.contains(":"))
@@ -329,10 +328,10 @@ public class ProjectDocModel {
return;
}
- val descriptionBlock = block(doc);
+ val descriptionBlock = block(overviewDoc);
val groupDiagram = new GroupDiagram(C4.of(sectionName, null));
- val table = table(doc);
+ val table = table(overviewDoc);
table.setTitle(String.format("Projects/Modules (%s)", sectionName));
table.setAttribute("cols", "3a,5a", true);
table.setAttribute("header-option", "", true);
@@ -408,14 +407,14 @@ public class ProjectDocModel {
// Group: org.apache.isis.commons
// Artifact: isis-commons
// Type: jar
- // Folder: \commons
+ // Directory: /commons
// ----
private String coordinates(ProjectNode module, String projRelativePath) {
val coors = new StringBuilder();
appendKeyValue(coors, "Group", module.getArtifactCoordinates().getGroupId());
appendKeyValue(coors, "Artifact", module.getArtifactCoordinates().getArtifactId());
appendKeyValue(coors, "Type", module.getArtifactCoordinates().getPackaging());
- appendKeyValue(coors, "Folder", projRelativePath);
+ appendKeyValue(coors, "Directory", projRelativePath.replaceAll("\\\\", "/"));
return String.format("%s\n%s",
module.getName(),
AsciiDocFactory.toString(doc->
@@ -475,13 +474,13 @@ public class ProjectDocModel {
}
private static String toAdocSection(String title, String content) {
-
+
//XXX collapsible will be supported with antora 3
// return AsciiDocFactory.toString(doc->{
// val collapsibleBlock = AsciiDocFactory.collapsibleBlock(doc, content);
// collapsibleBlock.setTitle(title);
// });
-
+
// render as Sidebar block for now
return String.format(".%s\n****\n%s\n****\n\n", title, content);
}
@@ -489,7 +488,7 @@ public class ProjectDocModel {
private static String toAdocListItem(String element) {
return String.format("* %s\n", element);
}
-
+
private static String toAdocCompactListItem(String element) {
return String.format("%s +\n", element);
}
diff --git a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocWriter.java b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocWriter.java
index 9be58c0..b8cc9ea 100644
--- a/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocWriter.java
+++ b/tooling/cli/src/main/java/org/apache/isis/tooling/cli/projdoc/ProjectDocWriter.java
@@ -41,7 +41,7 @@ final class ProjectDocWriter {
@SneakyThrows
static void write(
final @NonNull CliConfig cliConfig,
- final @NonNull Document systemSummaryAdoc,
+ final @NonNull Document overviewAdoc,
final @NonNull J2AdocContext j2aContext,
final @NonNull ProjectDocModel.Mode mode) {
@@ -67,7 +67,7 @@ final class ProjectDocWriter {
// write system overview
val overviewFile = new File(pagesFolder, overview.getSystemOverviewFilename());
log.info("writing system overview: {}", overviewFile.getName());
- docWriter.accept(systemSummaryAdoc, overviewFile);
+ docWriter.accept(overviewAdoc, overviewFile);
++writeCount;
}
diff --git a/tooling/java2adoc/src/main/java/org/apache/isis/tooling/j2adoc/J2AdocContext.java b/tooling/java2adoc/src/main/java/org/apache/isis/tooling/j2adoc/J2AdocContext.java
index e573c08..636f7ad 100644
--- a/tooling/java2adoc/src/main/java/org/apache/isis/tooling/j2adoc/J2AdocContext.java
+++ b/tooling/java2adoc/src/main/java/org/apache/isis/tooling/j2adoc/J2AdocContext.java
@@ -260,16 +260,20 @@ public class J2AdocContext {
public String xref(final @NonNull J2AdocUnit unit) {
- val xrefCoordinates = unit.getNamespace()
+ val xrefModule = unit.getNamespace()
.stream()
.skip(getNamespacePartsSkipCount())
+ .findFirst().get();
+ val xrefCoordinates = unit.getNamespace()
+ .stream()
+ .skip(getNamespacePartsSkipCount() + 1)
.collect(Can.toCan())
.add(unit.getCanonicalName())
.stream()
.collect(Collectors.joining("/"));
- val xref = String.format("xref:%s[%s]",
- String.format(getXrefPageIdFormat(), xrefCoordinates),
+ val xref = String.format("xref:s[%s]",
+ String.format(getXrefPageIdFormat(), xrefModule, xrefCoordinates),
unit.getFriendlyName());
return xref;
[isis] 01/02: ISIS-2444: fixes references to system overview
Posted by da...@apache.org.
This is an automated email from the ASF dual-hosted git repository.
danhaywood pushed a commit to branch ISIS-2444
in repository https://gitbox.apache.org/repos/asf/isis.git
commit 0c82a3a79c49a9cdaf5b1a48315740e74060cded
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Mon Feb 22 22:50:37 2021 +0000
ISIS-2444: fixes references to system overview
... use the new location
---
.../conguide/modules/documentation/pages/building-docs-and-website.adoc | 2 +-
antora/components/docs/modules/ROOT/pages/about.adoc | 2 +-
antora/components/docs/modules/ROOT/pages/landing-page/components.adoc | 2 +-
antora/components/docs/modules/ROOT/partials/module-nav/components.adoc | 2 +-
core/adoc/modules/ROOT/nav.adoc | 2 --
tooling/cli/adoc/modules/tooling-cli/pages/about.adoc | 2 +-
6 files changed, 5 insertions(+), 7 deletions(-)
diff --git a/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc b/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc
index 7e873ce..f1353a8 100644
--- a/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc
+++ b/antora/components/conguide/modules/documentation/pages/building-docs-and-website.adoc
@@ -54,5 +54,5 @@ Both scripts can be found at the root of this git repo.
== Updating the Generated System Overview
-The xref:system:generated:system-overview.adoc[System Overview] contains a set of `.adoc` files that are generated from Java classes.
+The xref:refguide:_overview:about.adoc[System Overview] contains a set of `.adoc` files that are generated from Java classes.
diff --git a/antora/components/docs/modules/ROOT/pages/about.adoc b/antora/components/docs/modules/ROOT/pages/about.adoc
index 7c30f5d..2f310ef 100644
--- a/antora/components/docs/modules/ROOT/pages/about.adoc
+++ b/antora/components/docs/modules/ROOT/pages/about.adoc
@@ -137,7 +137,7 @@ _Process_
_Design_
-* xref:system:generated:system-overview.adoc[System Overview]
+* xref:refguide:_overview:about.adoc[System Overview]
* xref:core:ROOT:about.adoc[Core Framework]
_Analysis_
diff --git a/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc b/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc
index 23195d4..79dd335 100644
--- a/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc
+++ b/antora/components/docs/modules/ROOT/pages/landing-page/components.adoc
@@ -7,7 +7,7 @@ This page provides user/config guides for each of the main components of the fra
== Overview
-xref:system:generated:system-overview.adoc[System Overview]
+xref:refguide:_overview:about.adoc[System Overview]
== Viewers
diff --git a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc b/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
index 482bc29..04c66d9 100644
--- a/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
+++ b/antora/components/docs/modules/ROOT/partials/module-nav/components.adoc
@@ -5,7 +5,7 @@
** Overview
-*** xref:system:generated:system-overview.adoc[System Overview]
+*** xref:refguide:_overview:about.adoc[System Overview]
** Viewers
diff --git a/core/adoc/modules/ROOT/nav.adoc b/core/adoc/modules/ROOT/nav.adoc
index 2285634..e5c95c0 100644
--- a/core/adoc/modules/ROOT/nav.adoc
+++ b/core/adoc/modules/ROOT/nav.adoc
@@ -3,5 +3,3 @@
include::core:ROOT:partial$component-nav.adoc[]
-* see also:
-** xref:system:generated:system-overview.adoc[System Overview]
diff --git a/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc b/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
index 11d1307..3418cfe 100644
--- a/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
+++ b/tooling/cli/adoc/modules/tooling-cli/pages/about.adoc
@@ -253,7 +253,7 @@ This command generates the _Document Global Index_ (`.adoc`) files.
Any class found with magic `{@index}` in its _java-doc_ section at type level, will be included with the _Document Global Index_.
-Asciidoc files may refer to the _Document Global Index_ via `xref` or `include` statements using paths such as `system:generated:index/applib/Xxx.adoc`.
+Asciidoc files may refer to the _Document Global Index_ via `xref` or `include` statements using paths such as `refguide:applib:index/annotation/Xxx.adoc`.
==== Usage