Skip to content

Commit 8f504a9

Browse files
franklinschmportiz08marinaaisaDobromir Hristovhqhhuang
committed
Initial commit for open source
Co-authored-by: Marcus Ortiz <[email protected]> Co-authored-by: Marina Aisa <[email protected]> Co-authored-by: Dobromir Hristov <[email protected]> Co-authored-by: Hanqing Huang <[email protected]> Co-authored-by: David Rönnqvist <[email protected]> Co-authored-by: Ethan Kusters <[email protected]>
0 parents  commit 8f504a9

File tree

522 files changed

+69757
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

522 files changed

+69757
-0
lines changed

‎.browserslistrc

+12
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2021 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
> 1%
10+
last 2 versions
11+
not ie > 0
12+
not dead

‎.editorconfig

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2021 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
[*.{js,jsx,ts,tsx,vue,scss}]
10+
indent_style = space
11+
indent_size = 2
12+
end_of_line = lf
13+
trim_trailing_whitespace = true
14+
insert_final_newline = true
15+
max_line_length = 100

‎.eslintrc.js

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
/**
2+
* This source file is part of the Swift.org open source project
3+
*
4+
* Copyright (c) 2021 Apple Inc. and the Swift project authors
5+
* Licensed under Apache License v2.0 with Runtime Library Exception
6+
*
7+
* See https://swift.org/LICENSE.txt for license information
8+
* See https://swift.org/CONTRIBUTORS.txt for Swift project authors
9+
*/
10+
11+
module.exports = {
12+
root: true,
13+
env: {
14+
node: true,
15+
},
16+
extends: [
17+
'plugin:vue/essential',
18+
'@vue/airbnb',
19+
],
20+
parserOptions: {
21+
parser: 'babel-eslint',
22+
},
23+
rules: {
24+
'no-console': process.env.NODE_ENV === 'production' ? [
25+
'error',
26+
{ allow: ['error', 'warn'] },
27+
] : 'off',
28+
'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off',
29+
indent: [
30+
'error', 2,
31+
{ ignoredNodes: ['TemplateLiteral'] },
32+
],
33+
'arrow-parens': ['error', 'as-needed', {
34+
requireForBlockBody: true,
35+
}],
36+
'template-curly-spacing': 'off',
37+
'vue/experimental-script-setup-vars': 'off',
38+
},
39+
overrides: [
40+
{
41+
files: ['*Icon.vue'],
42+
rules: {
43+
'max-len': 'off',
44+
},
45+
},
46+
{
47+
files: ['**/__mocks__/*.js'],
48+
env: {
49+
jest: true,
50+
},
51+
},
52+
{
53+
files: [
54+
'**/__tests__/*.{j,t}s?(x)',
55+
'**/tests/unit/**/*.spec.{j,t}s?(x)',
56+
],
57+
env: {
58+
jest: true,
59+
},
60+
},
61+
],
62+
};

‎.github/pull_request_template.md

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Bug/issue #, if applicable:
2+
3+
## Summary
4+
5+
_Provide a description of what your PR addresses, explaining the expected user experience.
6+
Also, provide an overview of your implementation._
7+
8+
## Dependencies
9+
10+
_Describe any dependencies this PR might have, such as an associated branch in another repository._
11+
12+
## Testing
13+
14+
_Describe how a reviewer can test the functionality of your PR. Provide test content to test with if
15+
applicable._
16+
17+
Steps:
18+
1. _Provide setup instructions._
19+
2. _Explain in detail how the functionality can be tested._
20+
21+
## Checklist
22+
23+
Make sure you check off the following items. If they cannot be completed, provide a reason.
24+
25+
- [ ] Added tests
26+
- [ ] Ran `npm test`, and it succeeded
27+
- [ ] Updated documentation if necessary

‎.gitignore

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# This source file is part of the Swift.org open source project
2+
#
3+
# Copyright (c) 2021 Apple Inc. and the Swift project authors
4+
# Licensed under Apache License v2.0 with Runtime Library Exception
5+
#
6+
# See https://swift.org/LICENSE.txt for license information
7+
# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
8+
9+
.DS_Store
10+
node_modules
11+
/dist
12+
13+
# local env files
14+
.env.local
15+
.env.*.local
16+
17+
# Log files
18+
npm-debug.log*
19+
yarn-debug.log*
20+
yarn-error.log*
21+
22+
# Editor directories and files
23+
.idea
24+
.vscode
25+
*.suo
26+
*.ntvs*
27+
*.njsproj
28+
*.sln
29+
*.sw*
30+
31+
__pycache__

‎CODE_OF_CONDUCT.md

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
# Code of Conduct
2+
3+
The code of conduct for this project can be found at https://swift.org/code-of-conduct.
4+
5+
<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->

‎CONTRIBUTING.md

+191
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,191 @@
1+
# Contributing to Swift-DocC-Render
2+
3+
## Introduction
4+
5+
### Welcome
6+
7+
Thank you for considering contributing to Swift-DocC-Render.
8+
9+
Please know that everyone is welcome to contribute to Swift-DocC-Render.
10+
Contributing doesn’t just mean submitting pull requests—there
11+
are many different ways for you to get involved,
12+
including answering questions on the
13+
[Swift Forums](https://forums.swift.org/c/development/swift-docc),
14+
reporting or screening bugs, and writing documentation.
15+
16+
No matter how you want to get involved,
17+
we ask that you first learn what’s expected of anyone who participates in
18+
the project by reading the [Swift Community Guidelines](https://swift.org/community/)
19+
as well as our [Code of Conduct](/CODE_OF_CONDUCT.md).
20+
21+
This document focuses on how to contribute code and documentation to
22+
this repository.
23+
24+
### Legal
25+
26+
By submitting a pull request, you represent that you have the right to license your
27+
contribution to Apple and the community, and agree by submitting the patch that your
28+
contributions are licensed under the Apache 2.0 license (see [`LICENSE.txt`](/LICENSE.txt)).
29+
30+
## Contributions Overview
31+
32+
Swift-DocC-Render is an open source project and we encourage contributions
33+
from the community.
34+
35+
### Contributing Code and Documentation
36+
37+
Before contributing code or documentation to Swift-DocC-Render
38+
we encourage you to first create an issue on [Swift JIRA](https://bugs.swift.org/)
39+
for a bug report or feature request.
40+
This will allow us to provide feedback on the proposed change.
41+
However, this is not a requirement. If your contribution is small in scope,
42+
feel free to open a PR without first creating an issue.
43+
44+
All changes to Swift-DocC-Render source must go through the PR review process before
45+
being merged into the `main` branch.
46+
See the [Code Contribution Guidelines](#code-contribution-guidelines) below for
47+
more details.
48+
49+
## Build and Run Swift-DocC-Render
50+
51+
### Run Steps
52+
53+
> Note: requires [Node.js](https://nodejs.org/en/download/) v14
54+
> and [npm](https://www.npmjs.com/package/npm) v6.14
55+
56+
1. Checkout this repository using:
57+
58+
```shell
59+
git clone [email protected]:apple/swift-docc-render.git
60+
```
61+
62+
2. Navigate to the root of your cloned repository with:
63+
64+
```shell
65+
cd swift-docc-render
66+
```
67+
68+
3. Install dependencies:
69+
70+
```shell
71+
npm install
72+
```
73+
74+
4. Run a local server with hot reload at [localhost:8080](http://localhost:8080/)
75+
76+
You may want to set an http endpoint as a proxy to handle data requests while developing locally.
77+
78+
```shell
79+
VUE_APP_DEV_SERVER_PROXY=https://localhost:8000 npm run serve
80+
```
81+
82+
As an alternative you can just create a `.env.development.local` file on the root of the project to add the `VUE_APP_DEV_SERVER_PROXY` env varible so you don't have to set it in the `npm run serve` script each time.
83+
84+
### Build Steps
85+
86+
To build Swift-DocC-Render for deployment, run the command below. The output will be generated inside the `dist` folder:
87+
88+
```shell
89+
npm run build
90+
```
91+
92+
## Testing Swift-DocC-Render using data from Swift-DocC
93+
94+
Follow [these steps](https://github.com/apple/swift-docc#using-docc-to-build-and-preview-documentation) to generate a documentation archive, set the path to your renderer and render locally your documentation using Swift-DocC-Render.
95+
96+
## Code Contribution Guidelines
97+
98+
### Overview
99+
100+
- Do your best to keep the git history easy to understand.
101+
102+
- Use informative commit titles and descriptions.
103+
- Include a brief summary of changes as the first line.
104+
- Describe everything that was added, removed, or changed, and why.
105+
106+
- All changes must go through the pull request review process.
107+
108+
### Pull Request Preparedness Checklist
109+
110+
When you're ready to have your change reviewed, please make sure you've completed the following requirements:
111+
112+
- [x] Add Swift's license header to the new files.
113+
114+
- [x] Add tests to cover any new functionality or to prevent regressions of a bug fix.
115+
116+
- [x] Run the `npm run test` script and confirm that the unit test, lint and license header checks pass.
117+
118+
- [x] Add source code documentation to all added coded that explains
119+
the new behavior.
120+
121+
### Opening a Pull Request
122+
123+
When opening a pull request, please make sure to fill out the pull request template
124+
and complete all tasks mentioned there.
125+
126+
Your PR should mention the number of the [Swift JIRA](https://bugs.swift.org/)
127+
issue your work is addressing (SR-NNNNN).
128+
129+
Most PRs should be against the `main` branch. If your change is intended
130+
for a specific release, you should also create a separate branch
131+
that cherry-picks your commit onto the associated release branch.
132+
133+
### Code Review Process
134+
135+
All PRs will need approval from someone on the core team
136+
(someone with write access to the repository) before being merged.
137+
138+
## Testing and Linting
139+
140+
Swift-DocC-Render is committed to maintaining a high level of code quality.
141+
Before opening a pull request, we ask that you:
142+
143+
1. Run the full test suite and confirm that it passes.
144+
145+
2. Write new tests to cover any changes you made.
146+
147+
### Tests and linting
148+
149+
Run the following script to:
150+
- Run unit tests with [Jest](https://jestjs.io/)
151+
- Find syntax errors with [ESLint](https://eslint.org/)
152+
- Check that all files have license headers
153+
154+
```shell
155+
npm run test
156+
```
157+
158+
Run an individual unit test suite:
159+
160+
```shell
161+
npm run test:unit tests/unit/path/to/spec.js
162+
```
163+
164+
Run unit tests and watch for changes:
165+
166+
```shell
167+
npm run test:unit:watch
168+
```
169+
170+
To manually lint your code for style issues, you can run the [ESLint](https://eslint.org/) suite:
171+
172+
```shell
173+
npm run lint
174+
```
175+
176+
If you want the linter to automatically fix the errors it finds, run:
177+
178+
```shell
179+
npm run lint:fix
180+
```
181+
182+
## Your First Contribution
183+
184+
Unsure of where to begin contributing to Swift-DocC-Render? You can start by looking at
185+
the bugs in the `Swift-DocC-Render` component with the `StarterBug` label on
186+
[Swift JIRA](https://bugs.swift.org/issues/?jql=project%20%3D%20SR%20AND%20status%20in%20(Open%2C%20Reopened)%20AND%20component%20%3D%20Swift-DocC-Render%20AND%20labels%20%3D%20StarterBug).
187+
188+
Once you've found an issue to work on,
189+
follow the above instructions for [Building Swift-DocC-Render](#build-and-run-swift-docc-render).
190+
191+
<!-- Copyright (c) 2021 Apple Inc and the Swift Project authors. All Rights Reserved. -->

0 commit comments

Comments
 (0)