docs: generated JSON schema reference, tidy up README and contrib docs #327

coopernetes · 2023-10-27T03:18:44Z

shorten the README to include minimal instructions. Link to doc site
for detailed documentation.
remove boilerplate from README for contributing steps. Moved those
guidelines to CONTRIBUTING doc
use simplified npx commands for executing git-proxy
using github.com/coveooss/json-schema-for-humans to generate a
readable document in Markdown form to display in doc site
include a config used by json-schema-for-humans (jhsf.config.json)
so that doc can be generated repeatably
add npm script to execute the CLI with the included config and format
into a proper MDX doc for Docusaurus to serve

Testing npx with the new release:

$ npx -- @finos/git-proxy@1.1.0
Need to install the following packages:
  @finos/git-proxy@1.1.0
Ok to proceed? (y) 
npm WARN deprecated mkdirp@0.3.0: Legacy versions of mkdirp are no longer supported. Please update to mkdirp 1.x. (Note that the API surface has changed to use Promises in 1.x.)
npm WARN deprecated @material-ui/styles@4.11.5: Material UI v4 doesn't receive active development since September 2021. See the guide https://mui.com/material-ui/migration/migration-v4/ to upgrade to v5.
npm WARN deprecated @material-ui/core@4.12.4: Material UI v4 doesn't receive active development since September 2021. See the guide https://mui.com/material-ui/migration/migration-v4/ to upgrade to v5.
creating user
        user=admin,
        gitAccount=none
        email=admin@place.com,
        admin=true
Service Listening on 8080
Listening on 8000

$ npx -- @finos/git-proxy --help
Usage: git-proxy [options]

Options:
      --help      Show help                                            [boolean]
      --version   Show version number                                  [boolean]
  -v, --validate  Check the proxy.config.json file in the current working
                  directory for validation errors.
  -c, --config    Path to custom git-proxy configuration file.
                                                  [default: "proxy.config.json"]
$ npx -- @finos/git-proxy --version
1.1.0
$ npx -- @finos/git-proxy
Service Listening on 8080
Listening on 8000

Running the new script:

$ npm run gen-schema-doc

> @finos/git-proxy@1.1.0 gen-schema-doc
> node ./scripts/doc-schema.js

== Generating schema.md ==
== Generated schema.md in 0:00:00.057090 ==

Wrote schema reference to ./website/docs/configuration/reference.mdx

netlify · 2023-10-27T03:18:49Z

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Name	Link
🔨 Latest commit	`3fe9b2b`
🔍 Latest deploy log	https://app.netlify.com/sites/endearing-brigadeiros-63f9d0/deploys/6578623b29bda10008576bec

coopernetes · 2023-10-27T03:29:30Z

@maoo @JamieSlome I'm assuming the netlify preview won't deploy until #325 is merged?

JamieSlome · 2023-10-27T04:26:23Z

@coopernetes - these deployments are being weird. I'm getting some PRs that are deploying, some that aren't.

maoo · 2023-10-27T11:31:05Z

I manually re-triggered the Netlify build, preview is available on https://deploy-preview-327--endearing-brigadeiros-63f9d0.netlify.app/ and looks great, TY @coopernetes !

Also left a comment on #325 , right now netlify behaves a bit randomly and would be great to solve it.

JamieSlome

Couple a of questions there for ya @coopernetes. Beautiful PR though ❤️

README.md

JamieSlome

Updated some of my comments; once addressed, this PR is ready to go 👍

website/docs/usage.mdx

website/docs/configuration/reference.mdx

website/docs/configuration/overview.mdx

coopernetes · 2023-11-11T21:54:58Z

@JamieSlome all the review comments should now be resolved and we have a lean README with minimal instructions. Leaving the full e2e working example to the docs. Let me know if any further changes are required.

README.md

coopernetes · 2023-11-24T05:45:37Z

Hmm... @maoo know why this is failing? I swear, this was deploying fine on a previous commit. And I can see in the MDX doc that we have matching closing tags so I don't know why the doc build is failing.

https://app.netlify.com/sites/endearing-brigadeiros-63f9d0/deploys/655f767daa9c240008ef812e

10:58:28 AM: [ERROR] Client bundle compiled with errors therefore further build is impossible.
10:58:28 AM: Error: MDX compilation failed for file "/opt/build/repo/website/docs/configuration/reference.mdx"
10:58:28 AM: Cause: Expected a closing tag for `</strong>` (19:1-19:10) before the end of `paragraph`

I can try rendering a different template using the new generator tooling for the JSON schema.

coopernetes · 2023-12-10T20:07:15Z

The build error is related to compliance with MDX that the json-schema-for-humans tool doesn't account for at the moment in its plain Markdown template. Related coveooss/json-schema-for-humans#223 and discussion on mdxjs https://github.com/orgs/mdx-js/discussions/2260

I'll push up a fix in the schema doc generation script to account for this.

- shorten the README to include minimal instructions. Link to doc site for detailed documentation. - remove boilerplate from README for contributing steps. Moved those guidelines to CONTRIBUTING doc - use simplified npx commands for executing git-proxy

- using github.com/coveooss/json-schema-for-humans to generate a readable document in Markdown form to display in doc site - include a config used by json-schema-for-humans (jhsf.config.json) so that doc can be generated repeatably - add npm script to execute the CLI with the included config and format into a proper MDX doc for Docusaurus to serve

* add rationale for forking and explaining the use of GitHub CLI in the introductory README

* make the output smaller * mention that the authorisedList is a configured list of repos permitted through the proxy

- generate doc now complies with MDX and compiles correctly with docusaurus - replace the title as per PR comments via script Signed-off-by: Thomas Cooper <thomas.cooper@rbc.com>

coopernetes · 2023-12-10T20:45:21Z

@JamieSlome @maoo the new docs are now fixed and rebased with all the updates from main. The site is built successfully with the generated schema reference doc. Preview is available here:

https://deploy-preview-327--endearing-brigadeiros-63f9d0.netlify.app/docs/configuration/reference

maoo

LGTM!

JamieSlome

LGTM! 🍰

docs: generated JSON schema reference, tidy up README and contrib docs

coopernetes force-pushed the chore/docs-npx branch from c78c755 to de5a1da Compare October 27, 2023 03:20

coopernetes changed the title ~~chore/docs npx~~ docs: generated JSON schema reference, tidy up README and contrib docs Oct 27, 2023

JamieSlome self-assigned this Oct 27, 2023

JamieSlome reviewed Oct 27, 2023

View reviewed changes

README.md Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

JamieSlome reviewed Oct 31, 2023

View reviewed changes

website/docs/usage.mdx Outdated Show resolved Hide resolved

JamieSlome reviewed Oct 31, 2023

View reviewed changes

website/docs/configuration/reference.mdx Outdated Show resolved Hide resolved

JamieSlome reviewed Oct 31, 2023

View reviewed changes

website/docs/configuration/overview.mdx Outdated Show resolved Hide resolved

coopernetes force-pushed the chore/docs-npx branch from e169e67 to 73fc148 Compare November 11, 2023 21:52

JamieSlome reviewed Nov 15, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

JamieSlome reviewed Nov 23, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

JamieSlome reviewed Nov 23, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

JamieSlome reviewed Nov 23, 2023

View reviewed changes

README.md Outdated Show resolved Hide resolved

coopernetes force-pushed the chore/docs-npx branch from b0cdf3d to f120b11 Compare December 10, 2023 20:34

coopernetes and others added 9 commits December 10, 2023 15:39

Update website/docs/usage.mdx

2516d6a

Update website/docs/configuration/overview.mdx

80f4444

Update website/docs/configuration/reference.mdx

5e9ce04

docs: clarify use of github CLI in README

d724442

* add rationale for forking and explaining the use of GitHub CLI in the introductory README

docs: remove extra comment, cfg clarification

6b4bf9f

* make the output smaller * mention that the authorisedList is a configured list of repos permitted through the proxy

Update README.md

0aaa400

Update README.md

edccc6e

JamieSlome and others added 2 commits December 10, 2023 15:39

Update README.md

083a764

docs: resolve mdx build errors

7750ca0

- generate doc now complies with MDX and compiles correctly with docusaurus - replace the title as per PR comments via script Signed-off-by: Thomas Cooper <thomas.cooper@rbc.com>

coopernetes force-pushed the chore/docs-npx branch from f120b11 to 7750ca0 Compare December 10, 2023 20:40

re-gen doc to trigger deploy

f47d0cd

coopernetes force-pushed the chore/docs-npx branch from 992c024 to f47d0cd Compare December 10, 2023 20:43

maoo approved these changes Dec 11, 2023

View reviewed changes

JamieSlome approved these changes Dec 12, 2023

View reviewed changes

Merge branch 'main' into chore/docs-npx

3fe9b2b

JamieSlome merged commit 9957131 into finos:main Dec 12, 2023

Psingle20 pushed a commit to Psingle20/git-proxy that referenced this pull request Nov 27, 2024

Merge pull request finos#327 from coopernetes/chore/docs-npx

8cf5bcd

docs: generated JSON schema reference, tidy up README and contrib docs

coopernetes deleted the chore/docs-npx branch February 23, 2025 20:41

docs: generated JSON schema reference, tidy up README and contrib docs #327

docs: generated JSON schema reference, tidy up README and contrib docs #327

Uh oh!

Conversation

coopernetes commented Oct 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Oct 27, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for endearing-brigadeiros-63f9d0 canceled.

Uh oh!

coopernetes commented Oct 27, 2023

Uh oh!

JamieSlome commented Oct 27, 2023

Uh oh!

maoo commented Oct 27, 2023

Uh oh!

JamieSlome left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

JamieSlome left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coopernetes commented Nov 11, 2023

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coopernetes commented Nov 24, 2023

Uh oh!

coopernetes commented Dec 10, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coopernetes commented Dec 10, 2023

Uh oh!

maoo left a comment

Choose a reason for hiding this comment

Uh oh!

JamieSlome left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

coopernetes commented Oct 27, 2023 •

edited

Loading

netlify bot commented Oct 27, 2023 •

edited

Loading

coopernetes commented Dec 10, 2023 •

edited

Loading