`new-extension`: docs link in README is broken

[becky-gilbert]

I used the new-extension tool to create an extension, but I noticed that the package README's documentation is broken. See the documentation link in my extension repo for an example. I think the issue is that the link inserts the package name between /blob/main/ and README.md - if you remove the package name, the link works.

Also, the README documentation URL points to... the README file, which is a little weird. Should that documentation link send people to the /docs/<package-name>.md file instead?

[becky-gilbert]

I wanted to make a PR for this, but I'm still confused about the way that the README and documentation files are used/referenced in these packages and want to double-check.

It looks to me like all three packages will (in some cases) prompt the user for the path to the README.md file, and use <package name>/README.md as the default:

jspsych-dev/packages/new-plugin/src/cli.js

Lines 211 to 221 in ff9911c

	// If not in a known jsPsych monorepo, ask for the path to the README.md file
	let readmePath;
	if (!cwdInfo.isContribRepo) {
	const remoteGitUrl = await getRemoteGitUrl();
	readmePath = await input({
	message: "Enter the path to the README.md file for this plugin package [Optional]:",
	default: `${getGitHttpsUrl(remoteGitUrl)}/plugin-${getHyphenateName(name)}/README.md`, // '/plugin-${name}/README.md' if not a Git repository
	});
	} else {
	readmePath = `https://github.com/${cwdInfo.repoSlug}/packages/plugin-${getHyphenateName(name)}/README.md`;
	}

jspsych-dev/packages/new-extension/src/cli.js

Lines 191 to 201 in ff9911c

	// If not in the jspsych-contrib repository, ask for the path to the README.md file
	let readmePath;
	if (!cwdInfo.isContribRepo) {
	const remoteGitUrl = await getRemoteGitUrl();
	readmePath = await input({
	message: "Enter the path to the README.md file for this extension package [Optional]:",
	default: `${getGitHttpsUrl(remoteGitUrl)}/extension-${getHyphenateName(name)}/README.md`, // '/extension-${name}/README.md' if not a Git repository
	});
	} else {
	readmePath = `https://github.com/jspsych/jspsych-contrib/packages/extension-${getHyphenateName(name)}/README.md`;
	}

jspsych-dev/packages/new-timeline/src/cli.js

Lines 191 to 201 in ff9911c

	// If not in the jspsych-timelines repository, ask for the path to the README.md file
	let readmePath;
	if (!cwdInfo.isTimelinesRepo) {
	const remoteGitUrl = await getRemoteGitUrl();
	readmePath = await input({
	message: "Enter the path to the README.md file for this timeline package [Optional]:",
	default: `${getGitHttpsUrl(remoteGitUrl)}/${getHyphenateName(name)}/README.md`, // '/${name}/README.md' if not a Git repository
	});
	} else {
	readmePath = `https://github.com/jspsych/jspsych-timelines/packages/${getHyphenateName(name)}/README.md`;
	}

But all three packages also ONLY use the readmePath for the documentation link:

jspsych-dev/packages/new-plugin/src/cli.js

Line 277 in ff9911c

.pipe(replace("{documentationUrl}", answers.readmePath))

jspsych-dev/packages/new-extension/src/cli.js

Line 261 in ff9911c

.pipe(replace("{documentationUrl}", answers.readmePath))

jspsych-dev/packages/new-timeline/src/cli.js

Line 260 in ff9911c

.pipe(replace("{documentationUrl}", answers.readmePath))

The README file itself is always created at the top-level due to copying the template file contents, so this readmePath value is never used to determine that file location (or for anything else). Thus I think it's safe to replace the README path with the docs path, and perhaps rename it for clarity.

Looking at the jsPsych contrib repo, it looks like most README files point to the docs/package-name.md file for the documentation link. There are a few that point back to the README itself, which might be because they were created with this CLI package.

Suggested change

I'd like to change the interactive mode prompt from "Enter the path to the README.md file for this plugin package [Optional]:" to "Enter the path to the documentation file for this plugin package [Optional]:", and change the default value from "/README.md" to "/docs/.md".

Is that ok? And can I also change the corresponding --readme-path flag for non-interactive mode to --documentationPath? Or are you concerned about backwards compatibility?