Skip to content

Commit

Permalink
Avoid saving *.md to docs/src, render directly to target directory
Browse files Browse the repository at this point in the history
  • Loading branch information
@crucialfelix
crucialfelix committed Dec 10, 2019
1 parent 26eba17 commit c790372
Showing 1 changed file with 51 additions and 29 deletions.
80 changes: 51 additions & 29 deletions tasks/make-docs.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,62 +6,83 @@ const fsp = fs.promises;
const { renderDocForName } = require("./render-api");

const root = path.resolve(path.join(__dirname, ".."));
const packagesRoot = path.join(root, "packages");
const docsSrc = path.join(root, "docs", "src", "packages");

// const docsRoot = path.join(root, "docs");
const repository = "https://github.com/crucialfelix/supercolliderjs";

const typedocRoot = "https://crucialfelix.github.io/supercolliderjs";

// Test locally with:
// TODO: should be a fixed path for each to api.md
const docsRoot = "http://localhost:3000/#";

const packageNames = async () => (await fsp.readdir(packagesRoot)).filter(name => name.match(/^[a-z\-]+$/));
async function fileExists(filePath) {
return fsp.stat(filePath).then(
const packageNames = async () =>
(await fsp.readdir(path.join(root, "packages"))).filter(name => name.match(/^[a-z\-]+$/));

async function fileExists(...paths) {
return fsp.stat(path.join(root, ...paths)).then(
stat => true,
err => false,
);
}

const readFile = (...paths) => fs.readFileSync(path.join(root, ...paths), { encoding: "utf-8" });

const triple = "```";

const partials = {
header: fs.readFileSync(path.join(root, "docs", "src", "partials", "header.md")).toString(),
footer: fs.readFileSync(path.join(root, "docs", "src", "partials", "footer.md")).toString(),
header: readFile("docs", "src", "partials", "header.md"),
footer: readFile("docs", "src", "partials", "footer.md"),
};

// template lambdas
/**
* Insert an example from /examples/
*/
const example = text => {
const body = fs.readFileSync(path.join(root, text));
const body = readFile(text);
const link = `${repository}/blob/develop/${text}`;
return `${triple}js\n${body}\n${triple}\n<small class="source-link"><a href=${link}>source</a></small>\n`;
};
/**
* Insert a link to the TypeDocs page.
* This was used when typedocs was rendered with it's default html export.
*
* @deprecated
* @param {*} text
*/
const typedocLink = text => {
const [title, link] = text.split(":", 2);
const body = `[${title}](${typedocRoot}${link})`;
return body;
};
/**
* Render Typedocs for an entity in package
* Entity can be the name of a module, class, function, interface etc.
* It searches down the API by name or "name" (with added quotes to detect module names).
* @param {*} text package:EntityName
*/
const renderApi = text => {
const [package, name] = text.split(":", 2);
return renderDocForName(package, name);
};

async function make(srcPath, destPath, data) {
const tplPath = path.join(root, srcPath);
if (!(await fileExists(tplPath))) {
await fsp.mkdir(path.dirname(tplPath), { recursive: true });
await fsp.writeFile(tplPath, "");
async function renderTplPath(srcPath, destPath, data) {
const absTplPath = path.join(root, srcPath);
if (!(await fileExists(srcPath))) {
await fsp.mkdir(path.dirname(absTplPath), { recursive: true });
await fsp.writeFile(absTplPath, "");
}
const tpl = (await fsp.readFile(tplPath)).toString();
const tpl = readFile(srcPath);
return renderTpl(tpl, destPath, data);
}

async function renderTpl(tpl, destPath, data) {
const content = Mustache.render(tpl, data, partials);
await fsp.writeFile(path.join(root, destPath), content);
}

async function parseSidebar() {
// auto generate md files if they are listed in the sidebar
const sidebar = await fsp.readFile(path.join(root, "docs", "_sidebar.md"), { encoding: "utf8" });
const sidebar = readFile("docs", "_sidebar.md");
const autos = {};
function pushAuto(package, title, filename) {
if (!autos[package]) {
Expand All @@ -79,6 +100,7 @@ async function parseSidebar() {
const title = match[1];
const package = match[2];
const filename = match[3];
// or api?
if (filename !== "README.md") {
pushAuto(package, title, filename);
}
Expand All @@ -93,7 +115,6 @@ function generateAutodocument(package, { title, filename }) {
const BBBL = "{{{";
const BBBR = "}}}";

const p = path.join(docsSrc, package, filename);
const fullname = filename.replace("_", "/").replace(".md", "");
console.log({ filename, fullname, title, package });

Expand All @@ -102,15 +123,13 @@ function generateAutodocument(package, { title, filename }) {
${BBL}#api${BBR}${package}:${fullname}${BBL}/api${BBR}
`;

console.log({ body, p });

fs.writeFileSync(p, body, { encoding: "utf-8" });
return body;
}

async function main(version) {
const packages = await packageNames();

const pkg = JSON.parse(await fsp.readFile(path.join(root, "package.json")));
const pkg = JSON.parse(readFile("package.json"));

const rootData = {
name: pkg.name,
Expand All @@ -127,12 +146,12 @@ async function main(version) {
};

// _coverpage
await make("docs/src/_coverpage.md", "docs/_coverpage.md", rootData);
await renderTplPath("docs/src/_coverpage.md", "docs/_coverpage.md", rootData);

const autos = await parseSidebar();

for (const pkgdir of packages) {
const pkg = JSON.parse(await fsp.readFile(path.join(packagesRoot, pkgdir, "package.json")));
const pkg = JSON.parse(readFile("packages", pkgdir, "package.json"));
const short = pkg.name.replace("@supercollider/", "");
const data = {
...rootData,
Expand All @@ -145,25 +164,28 @@ async function main(version) {

// generate autodocument for each entry in sidebar
for (const sidebarLink of autos[short] || []) {
generateAutodocument(short, sidebarLink);
if (!(await fileExists("docs/src/packages", short, sidebarLink.filename))) {
const tplBody = generateAutodocument(short, sidebarLink);
await renderTpl(tplBody, path.join("docs", "packages", pkgdir, sidebarLink.filename), data);
}
}

for (const filename of fs.readdirSync(path.join("docs/src/packages", pkgdir))) {
if (filename.endsWith(".md")) {
const tplPath = path.join("docs/src/packages", pkgdir, filename);

// Write it to docs
await make(tplPath, path.join("docs/packages", pkgdir, filename), data);
await renderTplPath(tplPath, path.join("docs/packages", pkgdir, filename), data);

if (filename === "README.md") {
// Write to packages for publishing to npm
await make(tplPath, path.join("packages", pkgdir, filename), data);
await renderTplPath(tplPath, path.join("packages", pkgdir, filename), data);

if (pkgdir === "supercolliderjs") {
// Is also the main page in docs
await make(tplPath, path.join("docs", "README.md"), data);
await renderTplPath(tplPath, path.join("docs", "README.md"), data);
// and main page on github
await make(tplPath, "README.md", data);
await renderTplPath(tplPath, "README.md", data);
}
}
}
Expand Down

0 comments on commit c790372

Please sign in to comment.