Gitbook rendering updates

[jacogr]

Ok, @chevdor is going to kill me...

• First off, this Closes Gitbook does not render nested md files #158
• API documentation for classes now are rendering correctly
• Removed the type-* from the doc build with a .nodoc file

Now for the long version -

• Had to move all the docs/.adoc to docs/.md - gitbook does not include linked *.md files when using the adoc plugin, so all links to the api, api-provider, etc. *.md files were broken
• Even at this point, the nested SUMMARY is an issue, so had to manually add the Api, {Ws,Http}Provider and ApiRx classes to get them to link

What this does not do -

• No fix for API documentation does not render correctly #154 atm, it still shows up incorrectly

[amaury1093]

The final result looks good, but it seems obscure to me how you got there. If I delete docs/ and generate build:htmldocs again, only the html folder is generated, not the .md.

The way I would do it:

1. Typedoc generates .md files from comments, and the .md files are the only things we commit in this repo. This way if people visits the repo, they can hop in the docs/ folder directly.

   • So remove --theme default --out docs/html in package.json
   • Remove all the html files

2. Let CI do gitbook build, and generate all the html in a separate the folder, zip it and push it to polkadot.js.org.

[amaury1093]

In package.json, you pass --theme default --out docs/html, which overwrites options here.

[jacogr]

Ahh, package.json is actually not used. (But I didn't want to remove it ... yet, it helps when you can actually test HTML from typedoc as well)

This is a whole sprawling thing, effectively what is actually called is the build-docs script, which is shared - https://github.com/polkadot-js/dev/blob/master/packages/dev/scripts/polkadot-dev-build-docs.sh

(Hence build calling build-ts & build-docs)

[amaury1093]

Ah, right, this is the obscure part I missed.

[jacogr]

Obscure is the right word, yes.

[jacogr]

That would be the idea, however since polkadot.js.org already has a site, not as easy. The best we can do is to use the GH repo /docs sharing atm :( (And even for that, have issues with e.g. /apps since that is already hosted on gh-pages)

I certainly want to move to e.g. a docs repo with all the stuff included, initially trying to get at least some basic content up around the API.

so yes, 100% right - lots of work remaining :(

[polkadot-js-bot]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.