Docusaurus documentation site

[mongodben]

add Docusaurus documentation site to project.

staging version of site: https://mongodben.github.io/Bluehawk

[cbush]

Is this related?

[mongodben]

yea it's required for the typedoc docusaurus plugin to work.

if this flag isn't enabled, the plugin throws the following error when it runs:

error msg

Error: ../src/bluehawk/actions/copy.ts:29:62 - error TS2571: Object is of type 'unknown'.

29     const message = `Could not load stats for ${rootPath}: ${error.message}`;
                                                                ~~~~~

Error: ../src/bluehawk/actions/copy.ts:50:76 - error TS2571: Object is of type 'unknown'.

50       const message = `Failed to copy file ${filePath} to ${targetPath}: ${error.message}`;
                                                                              ~~~~~

Error: ../src/bluehawk/actions/copy.ts:111:100 - error TS2571: Object is of type 'unknown'.

111       const message = `Failed to write file ${targetPath} (based on ${parseResult.source.path}): ${error.message}`;
                                                                                                       ~~~~~

Error: ../src/bluehawk/actions/snip.ts:162:95 - error TS2571: Object is of type 'unknown'.

162       const message = `Failed to write ${targetPath} (based on ${parseResult.source.path}): ${error.message}`;
                                                                                                  ~~~~~

Error: ../src/bluehawk/bluehawk.ts:132:3 - error TS2571: Object is of type 'unknown'.

132 ${e.stack}
      ~

Error: ../src/bluehawk/bluehawk.ts:162:65 - error TS2571: Object is of type 'unknown'.

162         `falling back to plaintext parser for ${source.path}: ${error.message}`
                                                                    ~~~~~

Error: ../src/bluehawk/parser/visitor/makeCstVisitor.ts:244:37 - error TS2345: Argument of type 'unknown' is not assignable to parameter of type 'Error'.

244             jsonErrorToVisitorError(error, json, {
                                        ~~~~~

Error: ../src/cli/cli.ts:45:7 - error TS2571: Object is of type 'unknown'.

45       error.message = `Plugin '${path}' register() failed with error: ${error.message}`;
         ~~~~~

Error: ../src/cli/cli.ts:45:73 - error TS2571: Object is of type 'unknown'.

45       error.message = `Plugin '${path}' register() failed with error: ${error.message}`;

[nlarew]

Looks like these are errors in our (Bluehawk) code. Do you think we could update bh to cast the unkown errors instead (in the future perhaps)?

unknown is technically more correct and in general I think it's best that we stick as closely as possible to default/strict typescript.

[mongodben]

i don't really understand the question, could you expand a bit?

[nlarew]

I'm mainly interested if the errors you see with { useUnknownInCatchVariables: true } are something we could fix by updating the bluehawk source code. If so, I think we should fix them (i.e. what they do on this page) and then enable useUnknownInCatchVariables here.

[nlarew]

I fixed this on our end in #76

Once we merge that can we try docusaurus with useUnknownInCatchVariables set to true?

[nlarew]

The /docs/docs/* directory structure feels a bit weird to me. Is this a docusaurus convention? Could we rename to something like /docs/content/* or something else that makes sense but reduces repetition?

[mongodben]

@nlarew having the subdirectory named docs is docusaurus convention. and i'd advocate we keep it as such. but we could certainly name the parent directory something else. so it's like OTHER_NAME/docs/*. open to ideas 😀

[cbush]

Do these files actually need to be committed or can they be added to gitignore and just generated on the fly (during github action)?

[mongodben]

i think .gitignore-ing them would make sense. will make that change.

[mongodben]

done

[cbush]

This is a nitpick but I find this was a much better name than just "deploy.yml". Deploy what? Maybe "deploy-docs.yaml"

[mongodben]

makes sense to me. renaming