Skip to content

Commit d2b932c

Browse files
JordonPhillipsJordonPhillips
authored
Merge pull request #6 from smithy-lang/sphinx
Add sphinx project generation
2 parents 992c06d + cad7c66 commit d2b932c

File tree

17 files changed

+315
-19
lines changed

17 files changed

+315
-19
lines changed

‎build.gradle‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,9 @@ subprojects {
3838
apply plugin: "java-library"
3939

4040
java {
41-
sourceCompatibility = JavaVersion.VERSION_17
42-
targetCompatibility = JavaVersion.VERSION_17
41+
toolchain {
42+
languageVersion = JavaLanguageVersion.of(17)
43+
}
4344
}
4445

4546
repositories {

‎settings.gradle‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,3 +23,4 @@ pluginManagement {
2323

2424
rootProject.name = "smithy-docgen"
2525
include(":smithy-docgen-core")
26+
include(":smithy-docgen-test")

‎smithy-docgen-core/build.gradle‎

Lines changed: 2 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,6 @@
11
/*
2-
* Copyright 2023 Amazon.com, Inc. or its affiliates. All Rights Reserved.
3-
*
4-
* Licensed under the Apache License, Version 2.0 (the "License").
5-
* You may not use this file except in compliance with the License.
6-
* A copy of the License is located at
7-
*
8-
* http://aws.amazon.com/apache2.0
9-
*
10-
* or in the "license" file accompanying this file. This file is distributed
11-
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
12-
* express or implied. See the License for the specific language governing
13-
* permissions and limitations under the License.
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0
144
*/
155

166
description = "This module contains support for generating API documentation " +

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSettings.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ public record DocSettings(ShapeId service, String format) {
4141
public static DocSettings from(ObjectNode pluginSettings) {
4242
return new DocSettings(
4343
pluginSettings.expectStringMember("service").expectShapeId(),
44-
pluginSettings.getStringMemberOrDefault("format", "markdown")
44+
pluginSettings.getStringMemberOrDefault("format", "sphinx-markdown")
4545
);
4646
}
4747
}

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/DocSymbolProvider.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -124,7 +124,7 @@ public Symbol toSymbol(Shape shape) {
124124
@Override
125125
public Symbol serviceShape(ServiceShape shape) {
126126
return getSymbolBuilder(shape)
127-
.definitionFile(getDefinitionFile(serviceShape, shape))
127+
.definitionFile(getDefinitionFile("index"))
128128
.build();
129129
}
130130

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/integrations/SphinxIntegration.java‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package software.amazon.smithy.docgen.core.integrations;
7+
8+
import java.util.List;
9+
import java.util.Set;
10+
import java.util.logging.Logger;
11+
import software.amazon.smithy.docgen.core.DocFormat;
12+
import software.amazon.smithy.docgen.core.DocGenerationContext;
13+
import software.amazon.smithy.docgen.core.DocIntegration;
14+
import software.amazon.smithy.docgen.core.DocSettings;
15+
import software.amazon.smithy.docgen.core.sections.sphinx.ConfSection;
16+
import software.amazon.smithy.docgen.core.sections.sphinx.MakefileSection;
17+
import software.amazon.smithy.docgen.core.sections.sphinx.WindowsMakeSection;
18+
import software.amazon.smithy.docgen.core.writers.SphinxMarkdownWriter;
19+
import software.amazon.smithy.model.shapes.ServiceShape;
20+
import software.amazon.smithy.utils.SmithyInternalApi;
21+
22+
/**
23+
* Adds Sphinx project scaffolding for compatible formats.
24+
*/
25+
@SmithyInternalApi
26+
public final class SphinxIntegration implements DocIntegration {
27+
private static final String MARKDOWN_FORMAT = "sphinx-markdown";
28+
private static final Set<String> FORMATS = Set.of(MARKDOWN_FORMAT);
29+
private static final Logger LOGGER = Logger.getLogger(SphinxIntegration.class.getName());
30+
31+
@Override
32+
public List<DocFormat> docFormats(DocSettings settings) {
33+
return List.of(
34+
new DocFormat(MARKDOWN_FORMAT, ".md", new SphinxMarkdownWriter.Factory())
35+
);
36+
}
37+
38+
@Override
39+
public void customize(DocGenerationContext context) {
40+
if (!FORMATS.contains(context.docFormat().name())) {
41+
LOGGER.finest(String.format(
42+
"Format %s is not a Sphinx-compatible format, skipping Sphinx project setup.",
43+
context.docFormat().name()
44+
));
45+
return;
46+
}
47+
// TODO: add some way to disable project file generation
48+
LOGGER.finest("Generating Sphinx project files.");
49+
writeConf(context);
50+
writeMakefile(context);
51+
}
52+
53+
private void writeConf(DocGenerationContext context) {
54+
var service = context.model().expectShape(context.settings().service(), ServiceShape.class);
55+
var serviceSymbol = context.symbolProvider().toSymbol(service);
56+
57+
context.writerDelegator().useFileWriter("content/conf.py", writer -> {
58+
writer.pushState(new ConfSection(context));
59+
writer.write("""
60+
# Configuration file for the Sphinx documentation builder.
61+
# For the full list of built-in configuration values, see the documentation:
62+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
63+
project = $1S
64+
version = $2S
65+
release = $2S
66+
templates_path = ["_templates"]
67+
html_static_path = ["_static"]
68+
html_theme = "alabaster"
69+
""",
70+
serviceSymbol.getName(),
71+
service.getVersion());
72+
73+
if (context.docFormat().name().equals(MARKDOWN_FORMAT)) {
74+
writer.write("""
75+
extensions = ["myst_parser"]
76+
myst_enable_extensions = [
77+
# Makes bare links into actual links
78+
"linkify",
79+
80+
# Used to write directives that can be parsed by normal parsers
81+
"colon_fence",
82+
]
83+
""");
84+
85+
}
86+
writer.popState();
87+
});
88+
}
89+
90+
private void writeMakefile(DocGenerationContext context) {
91+
context.writerDelegator().useFileWriter("Makefile", writer -> {
92+
writer.pushState(new MakefileSection(context));
93+
writer.writeWithNoFormatting("""
94+
# Minimal makefile for Sphinx documentation
95+
# You can set these variables from the command line, and also
96+
# from the environment for the first two.
97+
SPHINXOPTS ?=
98+
SPHINXBUILD ?= sphinx-build
99+
SOURCEDIR = content
100+
BUILDDIR = build
101+
102+
# Put it first so that "make" without argument is like "make help".
103+
help:
104+
\t@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
105+
106+
.PHONY: help Makefile
107+
108+
# Catch-all target: route all unknown targets to Sphinx using the new
109+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
110+
%: Makefile
111+
\t@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
112+
""");
113+
writer.popState();
114+
});
115+
116+
context.writerDelegator().useFileWriter("make.bat", writer -> {
117+
writer.pushState(new WindowsMakeSection(context));
118+
writer.write("""
119+
@ECHO OFF
120+
121+
pushd %~dp0
122+
123+
REM Command file for Sphinx documentation
124+
125+
if "%SPHINXBUILD%" == "" (
126+
set SPHINXBUILD=sphinx-build
127+
)
128+
set SOURCEDIR=content
129+
set BUILDDIR=build
130+
131+
%SPHINXBUILD% >NUL 2>NUL
132+
if errorlevel 9009 (
133+
echo.
134+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
135+
echo.installed, then set the SPHINXBUILD environment variable to point
136+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
137+
echo.may add the Sphinx directory to PATH.
138+
echo.
139+
echo.If you don't have Sphinx installed, grab it from
140+
echo.https://www.sphinx-doc.org/
141+
exit /b 1
142+
)
143+
144+
if "%1" == "" goto help
145+
146+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
147+
goto end
148+
149+
:help
150+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
151+
152+
:end
153+
popd
154+
""");
155+
writer.popState();
156+
});
157+
}
158+
}

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/sections/sphinx/ConfSection.java‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package software.amazon.smithy.docgen.core.sections.sphinx;
7+
8+
import software.amazon.smithy.docgen.core.DocGenerationContext;
9+
import software.amazon.smithy.utils.CodeSection;
10+
11+
/**
12+
* Generates the {@code conf.py} file for sphinx.
13+
* @see <a href="https://www.sphinx-doc.org/en/master/usage/configuration.html">
14+
* sphinx config docs</a>
15+
* @param context The context used to generate documentation.
16+
*/
17+
public record ConfSection(DocGenerationContext context) implements CodeSection {
18+
}

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/sections/sphinx/MakefileSection.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package software.amazon.smithy.docgen.core.sections.sphinx;
7+
8+
import software.amazon.smithy.docgen.core.DocGenerationContext;
9+
import software.amazon.smithy.utils.CodeSection;
10+
11+
/**
12+
* Generates a Makefile that wraps sphinx-build with default arguments.
13+
* @param context The context used to generate documentation.
14+
*/
15+
public record MakefileSection(DocGenerationContext context) implements CodeSection {
16+
}

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/sections/sphinx/WindowsMakeSection.java‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
/*
2+
* Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
3+
* SPDX-License-Identifier: Apache-2.0
4+
*/
5+
6+
package software.amazon.smithy.docgen.core.sections.sphinx;
7+
8+
import software.amazon.smithy.docgen.core.DocGenerationContext;
9+
import software.amazon.smithy.utils.CodeSection;
10+
11+
/**
12+
* Generates a batch script that wraps sphinx-build with default arguments.
13+
* @param context The context used to generate documentation.
14+
*/
15+
public record WindowsMakeSection(DocGenerationContext context) implements CodeSection {
16+
}

‎smithy-docgen-core/src/main/java/software/amazon/smithy/docgen/core/writers/MarkdownWriter.java‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@
1515
* Writes documentation in <a href="https://spec.commonmark.org">CommonMark</a> format.
1616
*/
1717
@SmithyUnstableApi
18-
public final class MarkdownWriter extends DocWriter {
18+
public class MarkdownWriter extends DocWriter {
1919

2020
/**
2121
* Constructor.

0 commit comments

Comments
 (0)