[D4.2] Write documentation

[esteblock]

Write in the ./docs folder. Gitbook: https://soroban-react.gitbook.io/

[esteblock]

• [ ] Add jsdoc
• [ ] Configure script to use jsdoc and compile markdown documentation in ./docs folder
• [ ] Write documentation of each function

[esteblock]

Check https://stackoverflow.com/questions/15694267/how-to-easily-create-github-friendly-markdown-for-documented-javascript-function

[mauroepce]

Working on this branch: https://github.com/mauroepce/soroban-react/tree/soroban-documentation Tasks done:

1. Project forked
2. soroban-documentation branch created
3. Dependencies installed to work on documentation:

• prettierrc: setup Prettier, auto-format to improve readability.
• jsdoc: Automatically generate documentation from comments in code.
• jsdoc-to-markdown: Converts documentation from JSDoc to Markdown, for display on GitHub.
• jsdoc-babel: Allows JSDoc to interpret ES6 code and TypeScript using Babel.

4. "doc" script created to looks for TypeScript files (*.ts) in all subfolders of packages, and generates documentation based on the comments in these files. The resulting documentation is saved in docs/DOCS.md
5. I created a configuration file for JSDoc jsdoc.json

[mauroepce]

I was going to start to work on the documentation and I've encountered a problem in the index.tsx file in the package "chains" with references to FUTURENET and SANDBOX in SorobanClient.Networks. When trying to reference these networks I get the following errors:

Property 'FUTURENET' does not exist on type 'typeof Networks' Property 'SANDBOX' does not exist on type 'typeof Networks'

I've searched the documentation and repository of "soroban-client" but haven't found any mention of FUTURENET or SANDBOX that can help me solve this problem.

[mauroepce]

I opened an issue in the "soroban-client" repository to help me solve the FUTURENET and SANDBOX problem.

Here is the link to the issue: https://github.com/stellar/js-soroban-client/issues/104

I'll still continue with the documentation and then I'll do the code modifications.

[mauroepce]

I filled in the comments for the documentation of the index.tsx code inside the package chain. The only problem I'm having is that the script isn't recognizing comments inside .tsx files inside packages. Pending to be resolved.

[mauroepce]

Had a problem trying to run prettier on any tsx file. The warnings were as follows:

• [warn] jsxBracketSameLine is deprecated.
• [warn] Ignored unknown option { importOrder: ["react", "<THIRD_PARTY_MODULES>", "components/*", "app/*|config/*|interfaces/*|stories/*", "^[./ ]"] }.
• [warn] Ignored unknown option { importOrderSeparation: true }

I solved doing the following in the .prettierrc config file:

• Replaced "jsxBracketSameLine" by "bracketSameLine"
• The "importOrder" and "importOrderSeparation" issue was because the plugin @trivago/prettier-plugin-sort-imports was not installed. Now i'ts working

Aditional:

• Created a "prettier-format" script that looks for all the ts and tsx files under the packages folder and apply the config format.

[mauroepce]

There was an error in multiples files inside package's folder:

• Most files in the "packages" folder had an import error Cannot find module '@soroban-react/[package]' or its corresponding type declarations.ts(2307).

What was causing this:

• tsconfig.json file in the root directory wasn't configured for a monorepo environment.

Solved doing the following:

• The tsconfig.json file was adjusted, particularly the paths option, to map to where the modules reside. The final code looks like this:

{
  "extends": "@tsconfig/recommended/tsconfig.json",
  "compilerOptions": {
    "module": "CommonJS",
    "declaration": true,
    "moduleResolution": "Node",
    "baseUrl": ".",
    "paths": {
      "@soroban-react/*": ["packages/*/src"]
    }
  },
  "exclude": ["**/*.spec.ts"]
}

This tells TypeScript to look in the "packages/*/src" directory when an import starts with "@soroban-react/", resolving the import error.

[mauroepce]

I was having too much problems with JSDoc to create the documentation. JSDoc was still having trouble understanding the TypeScript/JSX code it's trying to parse. I think it may be because:

• The library's typescript code uses a syntax or feature that is not supported by JSDoc or the plugins being used.
• There is some kind of configuration missing from JSDoc or one of its plugins to allow it to fully understand the code.

Solution:

• I installed TypeDoc as it is a TypeScript-specific documentation generation tool, and it should be able to handle any valid TypeScript code.

[mauroepce]

Documentation generation with TYPEDOC, ready

Script Summary:

• Configured the Typedoc documentation generator to generate documentation for TypeScript files in the specified directorie /packages.
• The configuration was done using the typedoc.json file, which included the entry points (.tsx files) for each package.
• Setted the output directory to "docs" and excluded the "node_modules" directory.
• Excluded external and private symbols and enabled the generation of a README file.
• The "typedoc-plugin-markdown" plugin was used to generate Markdown documentation.
• Finally, was added a script in the package.json file to run the Typedoc command.

Documentation Generation:

• You can ran the typedoc command, either using npx typedoc or yarn typedoc, to generate the documentation based on the configured settings.
• Typedoc parsed the TypeScript files in the specified entry points and generated Markdown documentation in the "docs" directory.
• The documentation includes information about exported symbols, modules, classes, interfaces, and their respective comments.
• The generated documentation serves as a reference for developers and provides an overview of the code structure and API usage within the project.

[mauroepce]

Updates to the README.md file on the root directory:

1. Added instructions for generating documentation using Typedoc:

• Included a script and explanation of how to execute the Typedoc command.

2. Added a "prettier-format" script that automatically formats TypeScript (.ts) and TypeScript JSX (.tsx) files in the packages directory.

• Added the "prettier-format" script and the explanation of how it works.

[mauroepce]

Today I was focused on being able to publish to gitbook the documentation generated by typedoc and combined with additional folders added to the docs folder.

updates:

• currently the automatically generated documentation is being stored in a new folder called Technical-docs in the path docs/Technical-docs

• Additionally, the new folder structure is as follows: . ├── docs │ ├── Technical-docs │ │ ├── interfaces │ │ ├── modules │ │ └── README.md │ ├── Tutorial │ │ └── README.md │ ├── README.md │ └── SUMMARY.md

• Updated and summarized documentation of what the soroban-react library does as well as key features and the most important utilities and components was added.

Issues:

• I am not able to show the content of:

1. the README.md in Tutorial and
2. the .md files inside interfaces and modules ofTechnical-docs

• Basically the technicals-docs folder cannot be modified much since typedoc automatically generates the modules and interfaces folders so you can't add new folders as they will be deleted in the future if you run the script again

Solution: I'm looking at using the .gitbook.yaml to create the structure or using a SUMMARY.md within the docs.

[esteblock]

Close because will update doc in a new issue