We have already documented the process of reproducing our code on developer PC ( including docker …) So now we should help programmers understand the code that we have create and it’s general use.
For this,for any project that we have :
1. We should add a Readme.md file to explain the project
2. We should add documentation for any class
3. We should generate the documentation for any class in a readable form ( preferably html)
3. We should deploy somewhere the documentation
For the first point,this is very easy ( although painful to write ). However,we should add a link to the 4th point,the link to the documentation.
For point 2 and 3 (adding documentation for any class and generating html ),we could use https://typedoc.org/ .
And,because we are used to docker,I created build_code_documentation.txt docker file that runs typedoc on every project
FROM node:10
WORKDIR /app
WORKDIR /app
COPY package.json ./package.json
COPY bingo-cards-api/package.json ./bingo-cards-api/package.json
COPY bingo-cards-api-objects/package.json ./bingo-cards-api-objects/package.json
COPY bingo-cards-ui/package.json ./bingo-cards-ui/package.json
COPY bingo-meeting-console/package.json ./bingo-meeting-console/package.json
COPY bingo-meeting-objects/package.json ./bingo-meeting-objects/package.json
COPY bingo-meeting-objects-test/package.json ./bingo-meeting-objects-test/package.json
COPY yarn.lock ./yarn.lockRUN yarn install
COPY . ./
RUN npm install –global typedoc
RUN yarn build
RUN typedoc –mode file –out docs/source/bingo-cards-api –ignoreCompilerErrors –excludePrivate –excludeProtected bingo-cards-api/src
RUN typedoc –mode file –out docs/source/bingo-cards-api-objects –ignoreCompilerErrors –excludePrivate –excludeProtected bingo-cards-api-objects/src
RUN typedoc –mode file –out docs/source/bingo-cards-ui –ignoreCompilerErrors –excludePrivate –excludeProtected bingo-cards-ui/src
RUN typedoc –mode file –out docs/source/bingo-meeting-console –ignoreCompilerErrors –excludePrivate –excludeProtected bingo-meeting-console
RUN typedoc –mode file –out docs/source/bingo-meeting-objects –ignoreCompilerErrors –excludePrivate –excludeProtected bingo-meeting-objects
RUN typedoc –mode file –out docs/source/bingo-meeting-objects-test –ignoreCompilerErrors –excludePrivate –excludeProtected bingo-meeting-objects-testCMD tail -f /dev/null
And the bat file just copy on hard disj
docker build .. -f docker_build_code_documentation.txt -t bingo_build_code_documentation
docker run -d –rm –name bingo_build_code_documentation_container bingo_build_code_documentation
docker cp bingo_build_code_documentation_container:/app/docs/source .
docker container kill bingo_build_code_documentation_container
For the last point,we can deploy documentation at github pages,in a separate folder in docs,named source ( we will just copy the files genetated by docker)
You can find the result of the documentation at
Leave a Reply