Add api page #32
No reviewers
jolheiser
silverwind
lunny
Labels
No Label
Kind/Breaking
Kind/Bug
Kind/Documentation
Kind/Enhancement
Kind/Feature
Kind/Security
Kind/Testing
Priority
Critical
Priority
High
Priority
Low
Priority
Medium
Reviewed
Confirmed
Reviewed
Duplicate
Reviewed
Invalid
Reviewed
Won't Fix
Status
Abandoned
Status
Blocked
Status
Need More Info
No Milestone
No Assignees
4 Participants
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: gitea/gitea-docusaurus#32
Loading…
Reference in New Issue
Block a user
No description provided.
Delete Branch "HesterG/gitea-docusaurus:add-api-page"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Changes
sedfor swagger.json for proper version and baseurl.Screenshots
Search:
1fba8113e4tobf6a012c6564f7420ab8to6dd6afb61dI get a JS OOM running this as well.
I'm not sure if that is a docusaurus issue or what, but it seems strange for the process to not be able to handle it.
Add
export NODE_OPTIONS="--max-old-space-size=4096"to Makefile to give v8 4GB heap size. IIRC, node by default still only allocates 2GB heap size for v8, which is too little for some of the more involved JS build processes.@ -33,4 +33,5 @@ jobs:- name: build siterun: |npm ciexport NODE_OPTIONS="--max-old-space-size=8192"Move it to Makefile so everyone benefits, not just actions. Also, 4096 is likely already sufficient as it doubles the default value.
I moved this to
install necessary toolsstep for now, because I am not very sure where this should be put inside makefile, do you have a suggestion?Update:
Looks like export is not working if moved to
install necessary toolsstep, so reverted it.I don't know the specifics of this projects, but
Makefileshould be the single entry point for all activities, so it seems only logical to me to either export it there, or do the more cautious variant of only setting it per command, e.g.I see, I changed the
npm run buildinto usingmakeso it worked as expected.Got it to build with the suggestion from silverwind.
This is really cool, I had to add a few things to the Makefile now that we have 1.21-dev, so my local server had three API docs to build.
I'm not sure how many we plan to have at once, but I have to say it was a very slow build and it chugged. Overall I like the idea to have the swagger info in the docs, but at least on my (admittedly older) machine it makes the build process a bit more painful.
Is there any way to make this an "optional" part of the build? That would at least make DX a bit easier.
Hi, I added options for start and build steps in
c62e7b8c35, so if donpm run start-noapiornpm run build-noapi, the api building step will be skipped. Please review if this is a proper way to do so, thanks.a5988d4925to62a6115b4fAlso, I recommend removing all the scripts in
package.jsonand move them toMakefile. Either use one or the other, but not both.I think the whole tranform can be in another PR, for this one, I seperated steps in
make buildintomake prepare-docsandmake buildand changednpm ci & npm run buildin action yaml files tomake buildfor theexport NODE_OPTIONSinmakefileto work.Also updated README
I guess I can follow up to this with the script moving.
@ -3,3 +1,1 @@elseSED_INPLACE := sed -i ''endifexport NODE_OPTIONS := "--max-old-space-size=8192"Is 4096 enough to make it work? Some people might not have so much free memory and we shouldn't take more than necessary.
I will try one
It works https://gitea.com/gitea/gitea-docusaurus/actions/runs/149
Found another way to improve api build for development:
Disable ssr and use client-only for api with reference to this discussion, but might be a bit hacky to implement:
https://gitea.com/HesterG/gitea-docusaurus/compare/add-api-page...HesterG/gitea-docusaurus:csr-api
In this implementation, if do
npm run start-noapiornpm run build-noapi, api pages will be csr and so api build is skipped during build time.776cd1fd97tod1ba4f3b62@silverwind Hi, which do you think is better for the
npm run start-noapiandnpm run build-noapiimplementation? (These are just for developement.)If there is no noticeable difference whether it's server- or client-rendered, I would probably prefer client-rendered.
BTW what I don't understand about the current build: How do you obtain the JSON files? Maybe we could have a small build script that does shallow checkout on the gitea repo to obtain the swagger file for each branch?
I think the current code could use some DRY. Have a YAML config that maps versions to branches, for example:
That way, you don't have to do so many changes in this repo when a new version releases. Also I recomment naming the swagger jsons
swagger-${version.name}.json.I think the main difference should be SEO. But if it is just for developement, should be fine. Pushed a commit to allow render api pages by csr.
They are inside prepare steps in
makefile, copied from gitea. There is a step cloning the specific branch.I can do this in next PR.
Done
WIP: Add api pageto Add api page