6 |
7 | _**ASoulDocs**_ is a stupid web server for multilingual documentation.
8 | 
on the top left corner of this document to get to a specific section of this guide quickly.
10 |
11 | ## New contributor guide
12 |
13 | To get an overview of the project, read the [README](/README.md). Here are some resources to help you get started with open source contributions:
14 |
15 | - [Finding ways to contribute to open source on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/finding-ways-to-contribute-to-open-source-on-github)
16 | - [Set up Git](https://docs.github.com/en/get-started/quickstart/set-up-git)
17 | - [GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow)
18 | - [Collaborating with pull requests](https://docs.github.com/en/github/collaborating-with-pull-requests)
19 |
20 | In addition to the general guides with open source contributions, you would also need to:
21 |
22 | - Have basic knowledge about HTTP, web applications development and programming in [Go](https://go.dev/).
23 | - Have a working local development setup with a reasonable good IDE or editor like [Visual Studio Code](https://code.visualstudio.com/docs/languages/go), [GoLand](https://www.jetbrains.com/go/) or [Vim](https://github.com/fatih/vim-go).
24 |
25 | ## Philosophy and methodology
26 |
27 | - [Talk, then code](https://www.craft.do/s/kyHVs6OoE4Dj5V)
28 |
29 | ## Issues
30 |
31 | ### Create a new issue
32 |
33 | - For questions, ask in [Discussions](https://github.com/asoul-sig/asouldocs/discussions).
34 | - [Check to make sure](https://docs.github.com/en/github/searching-for-information-on-github/searching-on-github/searching-issues-and-pull-requests#search-by-the-title-body-or-comments) someone hasn't already opened a similar [issue](https://github.com/asoul-sig/asouldocs/issues).
35 | - If a similar issue doesn't exist, open a new issue using a relevant [issue form](https://github.com/asoul-sig/asouldocs/issues/new/choose).
36 |
37 | ### Pick up an issue to solve
38 |
39 | - Scan through our [existing issues](https://github.com/asoul-sig/asouldocs/issues) to find one that interests you.
40 | - The [👋 good first issue](https://github.com/asoul-sig/asouldocs/issues?q=is%3Aissue+is%3Aopen+label%3A%22%F0%9F%91%8B+good+first+issue%22) is a good place to start exploring issues that are well-groomed for newcomers.
41 | - Do not hesitate to ask for more details or clarifying questions on the issue!
42 | - Communicate on the issue you are intended to pick up _before_ starting working on it.
43 | - Every issue that gets picked up will have an expected timeline for the implementation, the issue may be reassigned after the expected timeline. Please be responsible and proactive on the communication 🙇♂️
44 |
45 | ## Pull requests
46 |
47 | When you're finished with the changes, create a pull request, or a series of pull requests if necessary.
48 |
49 | Contributing to another codebase is not as simple as code changes, it is also about contributing influence to the design. Therefore, we kindly ask you that:
50 |
51 | - Please acknowledge that no pull request is guaranteed to be merged.
52 | - Please always do a self-review before requesting reviews from others.
53 | - Please expect code review to be strict and may have multiple rounds.
54 | - Please make self-contained incremental changes, pull requests with huge diff may be rejected for review.
55 | - Please use English in code comments and docstring.
56 | - Please do not force push unless absolutely necessary. Force pushes make review much harder in multiple rounds, and we use [Squash and merge](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges#squash-and-merge-your-pull-request-commits) so you don't need to worry about messy commits and just focus on the changes.
57 |
58 | ## Your PR is merged!
59 |
60 | Congratulations 🎉🎉 Thanks again for taking the effort to have this journey with us 🌟
61 |
--------------------------------------------------------------------------------
/.github/dependabot.yml:
--------------------------------------------------------------------------------
1 | # Docs: https://git.io/JCUAY
2 | version: 2
3 | updates:
4 | - package-ecosystem: "gomod"
5 | directory: "/"
6 | schedule:
7 | interval: "monthly"
8 | commit-message:
9 | prefix: "mod:"
10 | - package-ecosystem: "github-actions"
11 | directory: "/"
12 | schedule:
13 | interval: "monthly"
14 |
--------------------------------------------------------------------------------
/.github/pull_request_template.md:
--------------------------------------------------------------------------------
1 | ### Describe the pull request
2 |
3 | A clear and concise description of what the pull request is about, i.e. what problem should be fixed?
4 |
5 | Link to the issue:
6 |
7 | ### Checklist
8 |
9 | - [ ] I agree to follow the [Code of Conduct](https://go.dev/conduct) by submitting this pull request.
10 | - [ ] I have read and acknowledge the [Contributing guide](https://github.com/asoul-sig/asouldocs/blob/main/.github/contributing.md).
11 | - [ ] I have added test cases to cover the new code.
12 |
--------------------------------------------------------------------------------
/.github/workflows/codeql.yml:
--------------------------------------------------------------------------------
1 | # For most projects, this workflow file will not need changing; you simply need
2 | # to commit it to your repository.
3 | #
4 | # You may wish to alter this file to override the set of languages analyzed,
5 | # or to provide custom queries or build logic.
6 | #
7 | # ******** NOTE ********
8 | # We have attempted to detect the languages in your repository. Please check
9 | # the `language` matrix defined below to confirm you have the correct set of
10 | # supported CodeQL languages.
11 | #
12 | name: "CodeQL"
13 |
14 | on:
15 | push:
16 | branches: [ main ]
17 | pull_request:
18 | paths:
19 | - '.github/workflows/codeql.yml'
20 | schedule:
21 | - cron: '0 19 * * 0'
22 |
23 | jobs:
24 | analyze:
25 | name: Analyze
26 | runs-on: ubuntu-latest
27 |
28 | strategy:
29 | fail-fast: false
30 | matrix:
31 | language: [ 'go' ]
32 | # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
33 | # Learn more:
34 | # https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
35 |
36 | steps:
37 | - name: Checkout repository
38 | uses: actions/checkout@v4
39 | with:
40 | # We must fetch at least the immediate parents so that if this is
41 | # a pull request then we can checkout the head.
42 | fetch-depth: 2
43 |
44 | # If this run was triggered by a pull request event, then checkout
45 | # the head of the pull request instead of the merge commit.
46 | - run: git checkout HEAD^2
47 | if: ${{ github.event_name == 'pull_request' }}
48 |
49 | # Initializes the CodeQL tools for scanning.
50 | - name: Initialize CodeQL
51 | uses: github/codeql-action/init@v3
52 | with:
53 | languages: ${{ matrix.language }}
54 | # If you wish to specify custom queries, you can do so here or in a config file.
55 | # By default, queries listed here will override any specified in a config file.
56 | # Prefix the list here with "+" to use these queries and those in the config file.
57 | # queries: ./path/to/local/query, your-org/your-repo/queries@main
58 |
59 | # Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
60 | # If this step fails, then you should remove it and run the build manually (see below)
61 | - name: Autobuild
62 | uses: github/codeql-action/autobuild@v3
63 |
64 | # ℹ️ Command-line programs to run using the OS shell.
65 | # 📚 https://git.io/JvXDl
66 |
67 | # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
68 | # and modify them (or add more) to build your code if your project
69 | # uses a compiled language
70 |
71 | #- run: |
72 | # make bootstrap
73 | # make release
74 |
75 | - name: Perform CodeQL Analysis
76 | uses: github/codeql-action/analyze@v3
77 |
--------------------------------------------------------------------------------
/.github/workflows/docker.yml:
--------------------------------------------------------------------------------
1 | name: Docker
2 | on:
3 | push:
4 | branches:
5 | - main
6 | pull_request:
7 | paths:
8 | - 'Dockerfile'
9 | - '.github/workflows/docker.yml'
10 | release:
11 | types: [ published ]
12 |
13 | jobs:
14 | buildx:
15 | if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
16 | runs-on: ubuntu-latest
17 | permissions:
18 | actions: write
19 | contents: read
20 | packages: write
21 | steps:
22 | - name: Canel previous runs
23 | uses: styfle/cancel-workflow-action@0.12.1
24 | with:
25 | all_but_latest: true
26 | access_token: ${{ secrets.GITHUB_TOKEN }}
27 | - name: Checkout code
28 | uses: actions/checkout@v4
29 | - name: Set up QEMU
30 | uses: docker/setup-qemu-action@v3
31 | - name: Set up Docker Buildx
32 | id: buildx
33 | uses: docker/setup-buildx-action@v3
34 | with:
35 | config-inline: |
36 | [worker.oci]
37 | max-parallelism = 2
38 | - name: Inspect builder
39 | run: |
40 | echo "Name: ${{ steps.buildx.outputs.name }}"
41 | echo "Endpoint: ${{ steps.buildx.outputs.endpoint }}"
42 | echo "Status: ${{ steps.buildx.outputs.status }}"
43 | echo "Flags: ${{ steps.buildx.outputs.flags }}"
44 | echo "Platforms: ${{ steps.buildx.outputs.platforms }}"
45 | - name: Login to Docker Hub
46 | uses: docker/login-action@v3
47 | with:
48 | username: ${{ secrets.DOCKERHUB_USERNAME }}
49 | password: ${{ secrets.DOCKERHUB_TOKEN }}
50 | - name: Login to GitHub Container registry
51 | uses: docker/login-action@v3
52 | with:
53 | registry: ghcr.io
54 | username: ${{ github.repository_owner }}
55 | password: ${{ secrets.GITHUB_TOKEN }}
56 | - name: Build and push images
57 | uses: docker/build-push-action@v6
58 | with:
59 | context: .
60 | platforms: linux/amd64,linux/arm64,linux/arm/v7
61 | push: true
62 | tags: |
63 | unknwon/asouldocs:latest
64 | ghcr.io/asoul-sig/asouldocs:latest
65 | - name: Send email on failure
66 | uses: dawidd6/action-send-mail@v5
67 | if: ${{ failure() }}
68 | with:
69 | server_address: smtp.mailgun.org
70 | server_port: 465
71 | username: ${{ secrets.SMTP_USERNAME }}
72 | password: ${{ secrets.SMTP_PASSWORD }}
73 | subject: GitHub Actions (${{ github.repository }}) job result
74 | to: github-actions-8ce6454@unknwon.io
75 | from: GitHub Actions (${{ github.repository }})
76 | reply_to: noreply@unknwon.io
77 | body: |
78 | The job "${{ github.job }}" of ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }} completed with "${{ job.status }}".
79 |
80 | View the job run at: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
81 |
82 | buildx-pull-request:
83 | if: ${{ github.event_name == 'pull_request'}}
84 | runs-on: ubuntu-latest
85 | permissions:
86 | contents: read
87 | steps:
88 | - name: Checkout code
89 | uses: actions/checkout@v4
90 | - name: Set up Docker Buildx
91 | id: buildx
92 | uses: docker/setup-buildx-action@v3
93 | with:
94 | config-inline: |
95 | [worker.oci]
96 | max-parallelism = 2
97 | - name: Inspect builder
98 | run: |
99 | echo "Name: ${{ steps.buildx.outputs.name }}"
100 | echo "Endpoint: ${{ steps.buildx.outputs.endpoint }}"
101 | echo "Status: ${{ steps.buildx.outputs.status }}"
102 | echo "Flags: ${{ steps.buildx.outputs.flags }}"
103 | echo "Platforms: ${{ steps.buildx.outputs.platforms }}"
104 | - name: Compute short commit SHA
105 | uses: benjlevesque/short-sha@v3.0
106 | - name: Build and push images
107 | uses: docker/build-push-action@v6
108 | with:
109 | context: .
110 | platforms: linux/amd64
111 | push: true
112 | tags: |
113 | ttl.sh/asoul-sig/asouldocs-${{ env.SHA }}:1d
114 |
115 | # Updates to the following section needs to be synced to all release branches within their lifecycles.
116 | buildx-release:
117 | if: ${{ github.event_name == 'release' }}
118 | runs-on: ubuntu-latest
119 | permissions:
120 | actions: write
121 | contents: read
122 | packages: write
123 | steps:
124 | - name: Compute image tag name
125 | run: echo "IMAGE_TAG=$(echo $GITHUB_REF_NAME | cut -c 2-)" >> $GITHUB_ENV
126 | - name: Checkout code
127 | uses: actions/checkout@v4
128 | - name: Set up QEMU
129 | uses: docker/setup-qemu-action@v3
130 | - name: Set up Docker Buildx
131 | id: buildx
132 | uses: docker/setup-buildx-action@v3
133 | with:
134 | config-inline: |
135 | [worker.oci]
136 | max-parallelism = 2
137 | - name: Inspect builder
138 | run: |
139 | echo "Name: ${{ steps.buildx.outputs.name }}"
140 | echo "Endpoint: ${{ steps.buildx.outputs.endpoint }}"
141 | echo "Status: ${{ steps.buildx.outputs.status }}"
142 | echo "Flags: ${{ steps.buildx.outputs.flags }}"
143 | echo "Platforms: ${{ steps.buildx.outputs.platforms }}"
144 | - name: Login to Docker Hub
145 | uses: docker/login-action@v3
146 | with:
147 | username: ${{ secrets.DOCKERHUB_USERNAME }}
148 | password: ${{ secrets.DOCKERHUB_TOKEN }}
149 | - name: Login to GitHub Container registry
150 | uses: docker/login-action@v3
151 | with:
152 | registry: ghcr.io
153 | username: ${{ github.repository_owner }}
154 | password: ${{ secrets.GITHUB_TOKEN }}
155 | - name: Build and push images
156 | uses: docker/build-push-action@v6
157 | with:
158 | context: .
159 | platforms: linux/amd64,linux/arm64,linux/arm/v7
160 | push: true
161 | tags: |
162 | unknwon/asouldocs:${{ env.IMAGE_TAG }}
163 | ghcr.io/asoul-sig/asouldocs:${{ env.IMAGE_TAG }}
164 | - name: Send email on failure
165 | uses: dawidd6/action-send-mail@v5
166 | if: ${{ failure() }}
167 | with:
168 | server_address: smtp.mailgun.org
169 | server_port: 465
170 | username: ${{ secrets.SMTP_USERNAME }}
171 | password: ${{ secrets.SMTP_PASSWORD }}
172 | subject: GitHub Actions (${{ github.repository }}) job result
173 | to: github-actions-8ce6454@unknwon.io
174 | from: GitHub Actions (${{ github.repository }})
175 | reply_to: noreply@unknwon.io
176 | body: |
177 | The job "${{ github.job }}" of ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }} completed with "${{ job.status }}".
178 |
179 | View the job run at: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
180 |
--------------------------------------------------------------------------------
/.github/workflows/go.yml:
--------------------------------------------------------------------------------
1 | name: Go
2 | on:
3 | push:
4 | branches: [ main ]
5 | paths:
6 | - '**.go'
7 | - 'go.mod'
8 | - '.golangci.yml'
9 | - '.github/workflows/go.yml'
10 | pull_request:
11 | paths:
12 | - '**.go'
13 | - 'go.mod'
14 | - '.golangci.yml'
15 | - '.github/workflows/go.yml'
16 | env:
17 | GOPROXY: "https://proxy.golang.org"
18 |
19 | jobs:
20 | lint:
21 | name: Lint
22 | runs-on: ubuntu-latest
23 | steps:
24 | - name: Checkout code
25 | uses: actions/checkout@v4
26 | - name: Run golangci-lint
27 | uses: golangci/golangci-lint-action@v8
28 | with:
29 | version: latest
30 | args: --timeout=30m
31 | - name: Check Go module tidiness
32 | shell: bash
33 | run: |
34 | go mod tidy
35 | STATUS=$(git status --porcelain go.mod go.sum)
36 | if [ ! -z "$STATUS" ]; then
37 | echo "Running go mod tidy modified go.mod and/or go.sum"
38 | exit 1
39 | fi
40 |
41 | test:
42 | name: Test
43 | strategy:
44 | matrix:
45 | go-version: [ 1.21.x, 1.22.x ]
46 | platform: [ ubuntu-latest, macos-latest, windows-latest ]
47 | runs-on: ${{ matrix.platform }}
48 | steps:
49 | - name: Install Go
50 | uses: actions/setup-go@v5
51 | with:
52 | go-version: ${{ matrix.go-version }}
53 | - name: Checkout code
54 | uses: actions/checkout@v4
55 | - name: Run tests
56 | run: go test -v -race ./...
57 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Compiled Object files, Static and Dynamic libs (Shared Objects)
2 | *.o
3 | *.a
4 | *.so
5 |
6 | # Folders
7 | _obj
8 | _test
9 |
10 | # Architecture specific extensions/prefixes
11 | *.[568vq]
12 | [568vq].out
13 |
14 | *.cgo1.go
15 | *.cgo2.c
16 | _cgo_defun.c
17 | _cgo_gotypes.go
18 | _cgo_export.*
19 |
20 | _testmain.go
21 |
22 | *.exe
23 | *.test
24 | *.prof
25 | custom/
26 | data
27 | /.idea
28 | /asouldocs
29 | .DS_Store
30 | .task
31 | node_modules
32 |
--------------------------------------------------------------------------------
/.golangci.yml:
--------------------------------------------------------------------------------
1 | version: "2"
2 | linters:
3 | enable:
4 | - nakedret
5 | - rowserrcheck
6 | - unconvert
7 | - unparam
8 | settings:
9 | nakedret:
10 | max-func-lines: 0 # Disallow any unnamed return statement
11 | exclusions:
12 | generated: lax
13 | presets:
14 | - comments
15 | - common-false-positives
16 | - legacy
17 | - std-error-handling
18 | paths:
19 | - third_party$
20 | - builtin$
21 | - examples$
22 | formatters:
23 | enable:
24 | - gofmt
25 | - goimports
26 | exclusions:
27 | generated: lax
28 | paths:
29 | - third_party$
30 | - builtin$
31 | - examples$
32 |
--------------------------------------------------------------------------------
/CODEOWNERS:
--------------------------------------------------------------------------------
1 | # Default
2 | * @asoul-sig/core
3 |
--------------------------------------------------------------------------------
/Dockerfile:
--------------------------------------------------------------------------------
1 | FROM golang:alpine3.15 AS binarybuilder
2 | RUN apk --no-cache --no-progress add --virtual \
3 | build-deps \
4 | build-base \
5 | git
6 |
7 | # Install Task
8 | RUN wget --quiet https://github.com/go-task/task/releases/download/v3.12.0/task_linux_amd64.tar.gz -O task_linux_amd64.tar.gz \
9 | && sh -c 'echo "803d3c1752da31486cbfb4ddf7d8ba5e0fa8c8ebba8acf227a9cd76ff9901343 task_linux_amd64.tar.gz" | sha256sum -c' \
10 | && tar -xzf task_linux_amd64.tar.gz \
11 | && mv task /usr/local/bin/task
12 |
13 | WORKDIR /dist
14 | COPY . .
15 | RUN task build
16 |
17 | FROM alpine:3.15
18 | RUN echo https://dl-cdn.alpinelinux.org/alpine/edge/community/ >> /etc/apk/repositories \
19 | && apk --no-cache --no-progress add \
20 | ca-certificates \
21 | git
22 |
23 | # Install gosu
24 | RUN export url="https://github.com/tianon/gosu/releases/download/1.14/gosu-"; \
25 | if [ `uname -m` == "aarch64" ]; then \
26 | wget --quiet ${url}arm64 -O /usr/sbin/gosu \
27 | && sh -c 'echo "73244a858f5514a927a0f2510d533b4b57169b64d2aa3f9d98d92a7a7df80cea /usr/sbin/gosu" | sha256sum -c'; \
28 | elif [ `uname -m` == "armv7l" ]; then \
29 | wget --quiet ${url}armhf -O /usr/sbin/gosu \
30 | && sh -c 'echo "abb1489357358b443789571d52b5410258ddaca525ee7ac3ba0dd91d34484589 /usr/sbin/gosu" | sha256sum -c'; \
31 | else \
32 | wget --quiet ${url}amd64 -O /usr/sbin/gosu \
33 | && sh -c 'echo "bd8be776e97ec2b911190a82d9ab3fa6c013ae6d3121eea3d0bfd5c82a0eaf8c /usr/sbin/gosu" | sha256sum -c'; \
34 | fi \
35 | && chmod +x /usr/sbin/gosu
36 |
37 | WORKDIR /app/asouldocs/
38 | COPY --from=binarybuilder /dist/asouldocs .
39 |
40 | VOLUME ["/app/asouldocs/custom"]
41 | EXPOSE 5555
42 | CMD ["/app/asouldocs/asouldocs", "web"]
43 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2015 ASoulDocs
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | 
2 | 
3 |
4 |
6 |
7 | _**ASoulDocs**_ is a stupid web server for multilingual documentation.
8 | 
14 |
14 | 67 | {{.Node.Category}} 68 |
69 | {{end}} 70 | {{if .Fallback}} 71 |83 | {{call .Tr "docs::showing_default"}} 84 |
85 |
17 | 36 | {{call .Tr "home::tag_line"}} 37 |
38 |78 | {{call .Tr "home::multilingual_desc"}} 79 |
80 |89 | {{call .Tr "home::real_time_sync_desc"}} 90 |
91 |123 | {{call .Tr "home::customizable_desc"}} 124 |
125 |134 | {{call .Tr "home::comment_desc"}} 135 |
136 |