Github Pages doc site

[linonetwo]

Can you publish the docs to a github page? If the doc is generated from source, maybe this should be done in github action, and not commit to the master branch.

I mean files in ./docs/api seem to be generated. I can write a github action to generate it on the fly (so it don't need to exist in the repo), and make it a github pages. But I need the repo owner to open this

And I will go though the docs to add a menu for it (haven't seen a menu yet), and we can publish those markdown as doc site in github pages too.

[ralphhanna]

I have done what you requested, but not sure about next step

[linonetwo]

I will try make it a doc site. I'm still reading them these days to understand the structure.

I have a few experience with camunda , but very new to this.

[linonetwo]

By "go though the docs", I mean fixing these errors in the markdown...

But I can make a PR before I finish this, what do you think?

[ralphhanna]

sure go ahead

[linonetwo]

I'm using docusaurus to generate doc site, and I decided to use typedoc typedoc-plugin-markdown to generate API doc (delete the original things in /docs/api folder), because the original API doc are just empty placehoders, we won't lost any information when regenerating them from typescript typings.

After this I will make a PR.

[ralphhanna]

I am using typedoc-plugin-markdown as well in my local PC, I also generate TOC for some files Keep in mind I am re-writing/re-organizing the docs folder.

I just pushed the changes to rel2.0.0 branch,

Thanks

[linonetwo]

I rebased my PR based on yours.

Later we can delete /docs/api from the repo (also gitignore that folder), but only generate them in the CI. Additional info that needs to show in the /docs/api can be written as jsdoc in source code.

To properly gitignore the folder that we have committed, maybe you need to delete it from history and force push? I'm not sure, you can ask GPT or use https://www.atlassian.com/git/tutorials/saving-changes/gitignore#ignoring-a-previously-committed

After this, we can still generate it for local doc development, but not commit it.

[linonetwo]

To properly gitignore the folder that we have committed, maybe you need to delete it from history and force push? I'm not sure, you can ask GPT or use https://www.atlassian.com/git/tutorials/saving-changes/gitignore#ignoring-a-previously-committed

@ralphhanna can you do this? I think this might require force-push

I did it in #162 , seems don't need a force push. After merge it, You can try regenerate/modify things in docs/api folder, and see is it properly git ignored.

[ralphhanna]

I am getting lots of errors when using Docusaurus.

I have gone through major edit of all docs, almost done, in a week I should be complete. Here is what I have done to be able to see current docs:

1. Used root README.md as entry point to all docs
2. When I pushed my release api folder in github was empty
3. Changed .gitignore to put api back in github

Thanks

[linonetwo]

No! api folder should be ignored, and only generated using github actions! This what prevents git repo being huge.

If you have done this, you may need to follow https://www.atlassian.com/git/tutorials/saving-changes/gitignore#ignoring-a-previously-committed to delete them again. Trust me, this is the right choise.

[linonetwo]

to see current docs, you just need to merge this into master (of course, after you finish your 2.0 refactor).

Also I already fix all the errors when using Docusaurus, you just need to follow https://github.com/bpmnServer/bpmn-server/blob/rel2.0.0/docs/Development.md#document ,

npm run docs:generate before npm run docs:dev

[linonetwo]

2. When I pushed my release api folder in github was empty

I don't understand what you mean, this should not be pushed, just like those .js .map.js files.

If you want to change what in the /docs/api folder, you just need to change jsdocs in the .ts files.

And perhaps you can push your work more frequently, because I'm also reading those docs to understand ts logics, I may need your recent docs as a guide from an expert.

[ralphhanna]

My problem, after I pushed src, api was not generated, so README.md had many 404 errors. Was there something I am supposed to do first?

My flow was like this:

1. Generate API locally
2. Edit root README and docs locally , reference api's in my docs
3. Push (src,docs only) no api
4. Got 404 errors since there was no api files

Another question, where is the doc site? that Docusaurus generated for you?

Please go ahead and make changes I will not work on this for the next 2 days.

Thanks

[linonetwo]

I was playing video games today, sorry for the late reply.

4. Got 404 errors since there was no api files

Why will you get this, if you already done

1. Generate API locally

with npm run docs:generate ? I think this workflow works locally.

---

where is the doc site? that Docusaurus generated for you?

run npm run docs:dev will run it locally. And look at console for URL (I forget, might be localhost:3000 ?)

[linonetwo]

See my doc site of git-sync-js https://tiddly-gittly.github.io/git-sync-js/

and there is no docs folder in https://github.com/tiddly-gittly/git-sync-js , it generates completely in github actions.

[linonetwo]

@ralphhanna If you have any problem with doc site, fell free to ask me here. I'm recently building other opensource project, but always keep an eye on here, and looking forward to the 2.0 release.

[ralphhanna]

@linonetwo Hi, Ok build is complete without error but no menus or sidebar On local build, I get a menus and sidebar but on https://bpmnserver.github.io/bpmn-server/ none

[linonetwo]

The doc site is up now, also close this.

About sidebar, I'm not sure, isn't this the sidebar?