Skip to content

Commit 3a22fd3

Browse files
colinodellcolinodell
committed
Add docs site
1 parent 237120a commit 3a22fd3

40 files changed

+2231
-1
lines changed

‎.gitattributes

+2
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,9 @@
66
/.gitattributes export-ignore
77
/.github export-ignore
88
/.gitignore export-ignore
9+
/.nojekyll export-ignore
910
/.scrutinizer.yml export-ignore
11+
/docs export-ignore
1012
/phpcs.xml.dist export-ignore
1113
/phpstan.neon.dist export-ignore
1214
/phpunit.xml.dist export-ignore

‎.github/ISSUE_TEMPLATE/3_Question.md

+2
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ assignees: ''
77

88
---
99

10+
<!-- Have you tried checking the documentation first? https://config.thephpleague.com/ -->
11+
1012
## Question
1113

1214
<!-- Replace this with your question -->

‎.github/SUPPORT.MD

+1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
Here are some useful resources to help you use this project:
44

55
- [Project README](../README.md)
6+
- [Documentation](https://config.thephpleague.com/)
67

78
Need more help? Feel free to [ask a question](https://github.com/thephpleague/config/issues/new?labels=question) using our issue tracker and we'll do our best to answer it!
89

‎.github/workflows/build-jekyll-site-action/Dockerfile

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
FROM ruby:2.7-alpine
2+
3+
RUN apk add --no-cache git build-base libffi-dev
4+
5+
RUN bundle version
6+
7+
COPY entrypoint.sh /
8+
9+
ENTRYPOINT ["/entrypoint.sh"]

‎.github/workflows/build-jekyll-site-action/action.yml

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
name: 'Jekyll'
2+
description: 'A GitHub Action to build and publish Jekyll sites to GitHub Pages'
3+
inputs:
4+
jekyll_src:
5+
description: 'The Jekyll website source directory'
6+
required: false
7+
runs:
8+
using: 'docker'
9+
image: 'Dockerfile'
10+
args:
11+
- ${{ inputs.jekyll_src }}
12+
branding:
13+
icon: 'book'
14+
color: 'blue'

‎.github/workflows/build-jekyll-site-action/entrypoint.sh

+61
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
#!/bin/sh
2+
set -e
3+
4+
echo "Starting the Jekyll Action"
5+
6+
if [ -z "${JEKYLL_PAT}" ]; then
7+
echo "No token provided. Please set the JEKYLL_PAT environment variable."
8+
exit 1
9+
fi
10+
11+
if [ -n "${INPUT_JEKYLL_SRC}" ]; then
12+
JEKYLL_SRC=${INPUT_JEKYLL_SRC}
13+
echo "::debug ::Using parameter value ${JEKYLL_SRC} as a source directory"
14+
elif [ -n "${SRC}" ]; then
15+
JEKYLL_SRC=${SRC}
16+
echo "::debug ::Using SRC environment var value ${JEKYLL_SRC} as a source directory"
17+
else
18+
JEKYLL_SRC=$(find . -path ./vendor/bundle -prune -o -name '_config.yml' -exec dirname {} \;)
19+
echo "::debug ::Resolved ${JEKYLL_SRC} as a source directory"
20+
fi
21+
22+
cd $JEKYLL_SRC
23+
24+
echo "::debug ::Starting bundle install"
25+
bundle config path vendor/bundle
26+
bundle install --jobs 4 --retry 3
27+
echo "::debug ::Completed bundle install"
28+
29+
JEKYLL_ENV=production bundle exec jekyll build -d build
30+
echo "Jekyll build done"
31+
32+
cd build
33+
34+
# No need to have GitHub Pages to run Jekyll
35+
touch .nojekyll
36+
37+
# Is this a regular repo or an org.github.io type of repo
38+
case "${GITHUB_REPOSITORY}" in
39+
*.github.io) remote_branch="master" ;;
40+
*) remote_branch="gh-pages" ;;
41+
esac
42+
43+
if [ "${GITHUB_REF}" = "refs/heads/${remote_branch}" ]; then
44+
echo "Cannot publish on branch ${remote_branch}"
45+
exit 1
46+
fi
47+
48+
echo "Publishing to ${GITHUB_REPOSITORY} on branch ${remote_branch}"
49+
echo "::debug ::Pushing to https://${JEKYLL_PAT}@github.com/${GITHUB_REPOSITORY}.git"
50+
51+
remote_repo="https://${JEKYLL_PAT}@github.com/${GITHUB_REPOSITORY}.git" && \
52+
git init && \
53+
git config user.name "${GITHUB_ACTOR}" && \
54+
git config user.email "${GITHUB_ACTOR}@users.noreply.github.com" && \
55+
git add . && \
56+
git commit -m "jekyll build from Action ${GITHUB_SHA}" && \
57+
git push --force $remote_repo master:$remote_branch && \
58+
rm -fr .git && \
59+
cd ..
60+
61+
exit $?

‎.github/workflows/docs-lint.yml

+24
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
name: Lint Docs
3+
4+
on:
5+
push: ~
6+
pull_request: ~
7+
8+
jobs:
9+
docs-lint:
10+
name: Markdownlint
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v2
15+
16+
- uses: github/super-linter@v3
17+
env:
18+
DEFAULT_BRANCH: latest
19+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
20+
LINTER_RULES_PATH: '.' # From https://github.com/github/super-linter/pull/859#issuecomment-709625090
21+
22+
VALIDATE_MARKDOWN: true
23+
MARKDOWN_CONFIG_FILE: docs/.markdownlint.yml
24+
FILTER_REGEX_INCLUDE: '/docs/.*'

‎.github/workflows/docs.yml

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
name: Docs
2+
3+
on:
4+
schedule:
5+
- cron: '0 0 * * *'
6+
push:
7+
branches: [main]
8+
release:
9+
10+
jobs:
11+
github-pages:
12+
name: Build
13+
runs-on: ubuntu-16.04
14+
15+
steps:
16+
- uses: actions/checkout@v2
17+
18+
- uses: ./.github/workflows/build-jekyll-site-action
19+
with:
20+
jekyll_src: docs
21+
env:
22+
JEKYLL_GITHUB_TOKEN: ${{ secrets.JEKYLL_PAT }}
23+
JEKYLL_PAT: ${{ secrets.JEKYLL_PAT }}

‎.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
/.phpcs-cache
33
/.phpunit.result.cache
44
/build/
5+
/docs/_site/
56
composer.lock
67
composer.phar
78
/vendor/

‎README.md

+7-1
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ $config = new Configuration([
3434
'port' => Expect::int()->min(1)->max(65535),
3535
'ssl' => Expect::bool(),
3636
'database' => Expect::string()->required(),
37-
'username' => Expect::string()->nullable(),
37+
'username' => Expect::string()->required(),
3838
'password' => Expect::string()->nullable(),
3939
]),
4040
'logging' => Expect::structure([
@@ -77,13 +77,18 @@ $config->get('foo.bar');
7777
$config->exists('foo.bar'); // Returns `false`
7878
```
7979

80+
## 📓 Documentation
81+
82+
Full documentation can be found at [config.thephpleague.com][docs].
83+
8084
## 💭 Philosophy
8185

8286
This library aims to provide a **simple yet opinionated** approach to configuration with the following goals:
8387

8488
- The configuration should operate on **arrays with nested values** which are easily accessible
8589
- The configuration structure should be **defined with strict schemas** defining the overall structure, allowed types, and allowed values
8690
- Schemas should be defined using a **simple, fluent interface**
91+
- You should be able to **add and combine schemas but never modify existing ones**
8792
- Both the configuration values and the schema should be **defined and managed with PHP code**
8893
- Schemas should be **immutable**; they should never change once they are set
8994
- Configuration values should never define or influence the schemas
@@ -136,6 +141,7 @@ This will also test league/config against the latest supported spec.
136141

137142
This project is used by [league/commonmark][league-commonmark].
138143

144+
[docs]: https://config.thephpleague.com/
139145
[@colinodell]: https://www.twitter.com/colinodell
140146
[Composer]: https://getcomposer.org/
141147
[PHP League]: https://thephpleague.com

‎docs/.gitignore

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.jekyll-cache

‎docs/.markdownlint.yml

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
default: true
2+
line-length: false
3+
no-inline-html: false # Ignore for fontawesome usage
4+
5+
single-title:
6+
front_matter_title: '' # Ignore Jekyll titles as headers
7+
heading-style:
8+
style: atx
9+
10+
ul-style:
11+
style: dash
12+
13+
code-block-style:
14+
style: fenced
15+
code-fence-style:
16+
style: backtick

‎docs/1.0/basic-usage.md

+65
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
layout: default
3+
title: Basic Usage
4+
description: Basic usage of the league/config library
5+
---
6+
7+
# Basic Usage
8+
9+
There are three steps to using this library:
10+
11+
- [Defining the configuration schema](/1.0/schemas/)
12+
- The overall structure of the configuration
13+
- Required options, validation constraints, and default values
14+
- [Applying user-provided values](/1.0/setting-values/) against the schema
15+
- [Reading the validated options](/1.0/reading-values/) and acting on them
16+
17+
## Example
18+
19+
Simply define your configuration schema, set the values, and then fetch them where needed:
20+
21+
```php
22+
<?php
23+
24+
use League\Config\Configuration;
25+
use Nette\Schema\Expect;
26+
27+
// Define your configuration schema
28+
$config = new Configuration([
29+
'database' => Expect::structure([
30+
'driver' => Expect::anyOf('mysql', 'postgresql', 'sqlite')->required(),
31+
'host' => Expect::string()->default('localhost'),
32+
'port' => Expect::int()->min(1)->max(65535),
33+
'database' => Expect::string()->required(),
34+
'username' => Expect::string()->required(),
35+
'password' => Expect::string()->nullable(),
36+
]),
37+
'logging' => Expect::structure([
38+
'enabled' => Expect::bool()->default($_ENV['DEBUG'] == true),
39+
'path' => Expect::string()->assert(function ($path) { return \is_writeable($path); })->required(),
40+
]),
41+
]);
42+
43+
// Set the values somewhere
44+
$userProvidedValues = [
45+
'database' => [
46+
'driver' => 'mysql',
47+
'port' => 3306,
48+
'host' => 'localhost',
49+
'database' => 'myapp',
50+
'username' => 'myappdotcom',
51+
'password' => 'hunter2',
52+
],
53+
'logging' => [
54+
'path' => '/var/log/myapp.log',
55+
],
56+
];
57+
58+
// Merge those values into your configuration schema:
59+
$config->merge($userProvidedValues);
60+
61+
// Read the values and do stuff with them
62+
if ($config->get('logging.enabled')) {
63+
file_put_contents($config->get('logging.path'), 'Connecting to the database on ' . $config->get('database.host'));
64+
}
65+
```

‎docs/1.0/changelog.md

+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
layout: default
3+
title: Changelog
4+
description: Important changes made in recent releases
5+
---
6+
7+
# Changelog
8+
9+
All notable changes made in `1.x` releases are shown below. See the [full list of releases](/releases) for the complete changelog.
10+
11+
{% assign releases = site.github.releases | where_exp: "r", "r.name <= '2.0'" %}
12+
13+
{% for release in releases %}
14+
15+
## [{{ release.name }}]({{ release.html_url }}) - {{ release.published_at | date: "%Y-%m-%d" }}
16+
17+
{{ release.body | markdownify }}
18+
{% endfor %}
19+
20+
## Older Versions
21+
22+
Please see the [full list of releases](/releases) for the complete changelog.

‎docs/1.0/index.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
layout: default
3+
title: Overview
4+
---
5+
6+
# Overview
7+
8+
[![Author](https://img.shields.io/badge/[email protected]?style=flat-square)](https://twitter.com/colinodell)
9+
[![Latest Version](https://img.shields.io/packagist/v/league/config.svg?style=flat-square)](https://packagist.org/packages/league/config)
10+
[![Total Downloads](https://img.shields.io/packagist/dt/league/config.svg?style=flat-square)](https://packagist.org/packages/league/config)
11+
[![Software License](https://img.shields.io/badge/License-BSD--3-brightgreen.svg?style=flat-square)](LICENSE)
12+
[![Build Status](https://img.shields.io/github/workflow/status/thephpleague/config/Tests/main.svg?style=flat-square)](https://github.com/thephpleague/config/actions?query=workflow%3ATests+branch%3Amain)
13+
[![Coverage Status](https://img.shields.io/scrutinizer/coverage/g/thephpleague/config.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/config/code-structure)
14+
[![Quality Score](https://img.shields.io/scrutinizer/g/thephpleague/config.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/config)
15+
16+
{{ site.data.project.highlights.description }}
17+
18+
## Installation & Usage
19+
20+
This library can be installed via Composer:
21+
22+
```bash
23+
composer require league/config
24+
```
25+
26+
See the [installation](/1.0/installation/) section for more details, then check out the [basic usage](/1.0/basic-usage/) section for an example to get you started.

‎docs/1.0/installation.md

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
layout: default
3+
title: Installation
4+
description: Instructions on how to install the league/config library
5+
---
6+
7+
# Installation
8+
9+
The recommended installation method is via Composer.
10+
11+
```bash
12+
composer require "league/config:^1.0"
13+
```
14+
15+
Ensure that you’ve set up your project to [autoload Composer-installed packages](https://getcomposer.org/doc/01-basic-usage.md#autoloading).
16+
17+
## Versioning
18+
19+
[SemVer](http://semver.org/) will be followed closely. **It's highly recommended that you use [Composer's caret operator](https://getcomposer.org/doc/articles/versions.md#caret-version-range-) to ensure compatibility**; for example: `^1.0`. This is equivalent to `>=1.0 <2.0`.

0 commit comments

Comments
 (0)