Summary
The Setup your docs environment section in the docs contribution guide is out of date and points contributors to a Docsy theme directory that no longer exists in this repository layout.
Problem
The guide currently instructs contributors to run:
cd docs
git submodule update --init --recursive
npm install
cd themes/docsy
npm install
cd ..
In the current radius-project/docs repository:
- there is no
themes/docsy directory
npm install fails at the repository root because package.json is not there
- the actual Node project lives under
docs/docs
- Docsy is brought in via Hugo Modules rather than a checked-in theme folder
npm run dev fails because no dev script is defined in docs/package.json
This causes a confusing setup experience for contributors following the documented steps.
Evidence
A local reproduction following the current guide shows:
npm install fails in docs/ with ENOENT because package.json is missing
cd themes/docsy fails with no such file or directory
npm ci succeeds after changing into docs/docs
npm start successfully launches the local Hugo server from docs/docs
npm run dev fails because no dev script is defined
Suggested update
Revise the setup steps to match the current repository structure and Hugo Module-based theme usage. At minimum, update the instructions to:
- clone the repos as needed
- generate CLI docs
- change into
docs/docs
- run
npm ci
- run
npm start from docs/docs
- remove the
themes/docsy initialization step
- remove references to
npm run dev where no such script exists
Likely files to update
docs/content/contributing/contributing-docs/index.md
docs/README.md
- potentially any linked docs pages that duplicate the same outdated setup sequence
Acceptance criteria
- setup instructions no longer reference
themes/docsy
- setup instructions use the correct working directory for npm commands
- setup instructions use commands that exist in
docs/package.json
- a contributor can follow the documented steps from a fresh clone without hitting missing-directory or missing-package.json errors
- the contribution guide reflects the current Hugo Modules/Docsy setup
Summary
The Setup your docs environment section in the docs contribution guide is out of date and points contributors to a Docsy theme directory that no longer exists in this repository layout.
Problem
The guide currently instructs contributors to run:
In the current
radius-project/docsrepository:themes/docsydirectorynpm installfails at the repository root becausepackage.jsonis not theredocs/docsnpm run devfails because nodevscript is defined indocs/package.jsonThis causes a confusing setup experience for contributors following the documented steps.
Evidence
A local reproduction following the current guide shows:
npm installfails indocs/withENOENTbecausepackage.jsonis missingcd themes/docsyfails withno such file or directorynpm cisucceeds after changing intodocs/docsnpm startsuccessfully launches the local Hugo server fromdocs/docsnpm run devfails because nodevscript is definedSuggested update
Revise the setup steps to match the current repository structure and Hugo Module-based theme usage. At minimum, update the instructions to:
docs/docsnpm cinpm startfromdocs/docsthemes/docsyinitialization stepnpm run devwhere no such script existsLikely files to update
docs/content/contributing/contributing-docs/index.mddocs/README.mdAcceptance criteria
themes/docsydocs/package.json