Skip to content

Commit 1341ab6

Browse files
gildesmaraisgildesmarais
committed
docs: everything of configs readme
1 parent 56db2ed commit 1341ab6

File tree

10 files changed

+200
-3
lines changed

10 files changed

+200
-3
lines changed

‎configs-README.md‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
![html2rss logo](https://github.com/html2rss/html2rss/raw/master/support/logo.png)
2+
3+
# html2rss-configs
4+
5+
✌️ This repository contains [`html2rss`](https://github.com/html2rss/html2rss) _feed configs_ for many websites.
6+
👉 Find all _feed configs_ in the [`configs/` directory](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs).
7+
☝️ A handy usage method is via [`html2rss-web`](https://github.com/html2rss/html2rss-web).
8+
💪 Contributions are more than welcome!
9+
[Fork this repository](https://help.github.com/en/github/getting-started-with-github/fork-a-repo),
10+
add your _feed config_ and
11+
[create a pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request).
12+
13+
## Contributing
14+
15+
The html2rss "ecosystem" is a community project. We welcome contributions of all kinds. This includes new feed configs, suggesting and implementing features, providing bug fixes, documentation improvements, and any other kind of help.
16+
17+
### Adding a new feed config
18+
19+
Which way you choose to add a new feed config is up to you. You can do it manually or risk the "wizard-like" generator. Please [submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)!
20+
21+
After you're done, you can test your feed config by running `bundle exec html2rss feed lib/html2rss/configs/<domainname.tld>/<path>.yml`.
22+
23+
#### Prefered way: manually
24+
25+
1. Fork this repo and run `bundle install` (you need to have Ruby >= 3.1 installed).
26+
2. Create a new folder and file following ths convention: `lib/html2rss/configs/<domainname.tld>/<path>.yml`
27+
3. Create the feed config in the `<path>.yml` file.
28+
4. Add this spec file in the `spec/html2rss/configs/<domainname.tld>/<path>_spec.rb` file.
29+
30+
```ruby
31+
RSpec.describe '<domainname.tld>/<path>' do
32+
include_examples 'config.yml', described_class
33+
end
34+
```
35+
36+
#### Using the "wizard-like" generator
37+
38+
There's was a try to build a wizard like TUI based generator for that! 🆒 It hasn't seen much love, tho, but it might gets you going or crash in the middle of the process.
39+
40+
1. Fork this repo and run `bundle install` (you need to have Ruby >= 3.1 installed).
41+
2. Start the generator by typing: `bin/generator`
42+
3. Build your feed config and answer 'y' in the last step to create the files.
43+
4. Optionally, edit the created files. Read [`html2rss`'s README](https://github.com/html2rss/html2rss/blob/master/README.md) to see what is possible or browse [existing configs](https://github.com/html2rss/html2rss-configs/tree/master/lib/html2rss/configs) for inspiration.
44+
5. To test, run:
45+
`bundle exec html2rss feed lib/html2rss/configs/domainname.tld/whatever`
46+
47+
## Using dynamic parameters in `channel` attributes
48+
49+
When you're using dynamic parameters, you have to provide the parameters to the spec, too:
50+
51+
```ruby
52+
include_examples 'config.yml', 'domainname.tld/whatever.yml', id: 42
53+
```
54+
55+
CLI usage:
56+
57+
```sh
58+
bundle exec html2rss feed lib/html2rss/configs/domainname.tld/whatever id=42
59+
```
60+
61+
## Programmatic usage
62+
63+
Add to your Gemfile:
64+
65+
```ruby
66+
gem 'html2rss-configs', git: 'https://github.com/html2rss/html2rss-configs.git'
67+
```
68+
69+
Use it in your code:
70+
71+
```ruby
72+
require 'html2rss/configs'
73+
74+
config = Html2rss::Configs.find_by_name('domainname.tld/whatever')
75+
```
76+
77+
This will return the _feed config_.
78+
79+
## Usage with `html2rss-web`
80+
81+
If you're running [`html2rss-web`](https://github.com/html2rss/html2rss-web),
82+
you have nothing more to do! 🎉 Just request them from your instance at path: `/<domainname.tld/path>.rss` and you'll be served the RSS.
83+
84+
## CI: Building on the CI
85+
86+
Modifying existing or adding new _feed configs_ will trigger the CI to fetch the feed
87+
and check for the presence of feed items.

‎feed-directory/index.html‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
title: Feed Directory
44
nav_order: 2
55
noindex: true
6+
has_children: true
67
---
78

89
<div class="text-center">

‎get-involved/contributing.md‎

Lines changed: 20 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,24 @@ Here are some of the ways you can contribute to the `html2rss` project:
2525

2626
Are you missing an RSS feed for a website? You can create your own feed config and share it with the community. It's a great way to get started with `html2rss` and help other users.
2727

28-
[**Learn how to create a feed config**](https://github.com/html2rss/html2rss-configs)
28+
The html2rss "ecosystem" is a community project. We welcome contributions of all kinds. This includes new feed configs, suggesting and implementing features, providing bug fixes, documentation improvements, and any other kind of help.
29+
30+
Which way you choose to add a new feed config is up to you. You can do it manually. Please [submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)!
31+
32+
After you're done, you can test your feed config by running `bundle exec html2rss feed lib/html2rss/configs/<domainname.tld>/<path>.yml`.
33+
34+
#### Prefered way: manually
35+
36+
1. Fork this repo and run `bundle install` (you need to have Ruby >= 3.1 installed).
37+
2. Create a new folder and file following ths convention: `lib/html2rss/configs/<domainname.tld>/<path>.yml`
38+
3. Create the feed config in the `<path>.yml` file.
39+
4. Add this spec file in the `spec/html2rss/configs/<domainname.tld>/<path>_spec.rb` file.
40+
41+
```ruby
42+
RSpec.describe '<domainname.tld>/<path>' do
43+
include_examples 'config.yml', described_class
44+
end
45+
```
2946

3047
### 2. Improve this Website
3148

@@ -37,13 +54,13 @@ This website is built with Jekyll and is hosted on GitHub Pages. If you have any
3754

3855
The [`html2rss-web`](https://github.com/html2rss/html2rss-web) project is a web application that allows you to create and manage your RSS feeds through a user-friendly interface. You can host your own public instance to help other users create feeds.
3956

40-
[**Learn how to host a public instance**](https://github.com/html2rss/html2rss-web/wiki/Instances)
57+
[**Learn how to host a public instance**]({{ '/web-application/how-to/deployment' | relative_url }})
4158

4259
### 4. Improve the `html2rss` Gem
4360

4461
Are you a Ruby developer? You can help us improve the core `html2rss` gem. Whether you're fixing a bug, adding a new feature, or improving the documentation, your contributions are welcome.
4562

46-
[**Check out the repository on GitHub**](https://github.com/html2rss/html2rss)
63+
[**Check out the documentation for the `html2rss` Gem**]({{ '/ruby-gem/' | relative_url }})
4764

4865
### 5. Report Bugs & Discuss Features
4966

‎html2rss-configs/how-to/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: default
3+
title: How-To Guides
4+
has_children: true
5+
parent: html2rss-configs
6+
nav_order: 2
7+
---
8+
9+
# How-To Guides
10+
11+
This section provides practical guides on how to perform specific tasks with `html2rss-configs`.

‎html2rss-configs/how-to/usage-with-web.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: default
3+
title: Usage with html2rss-web
4+
parent: How-To Guides
5+
grand_parent: html2rss-configs
6+
nav_order: 3
7+
---
8+
9+
# Usage with `html2rss-web`
10+
11+
If you're running [`html2rss-web`](https://github.com/html2rss/html2rss-web), you have nothing more to do! Just request them from your instance at path: `/<domainname.tld/path>.rss` and you'll be served the RSS.

‎html2rss-configs/index.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
layout: default
3+
title: html2rss-configs
4+
has_children: true
5+
nav_order: 5
6+
---
7+
8+
# html2rss-configs Documentation
9+
10+
This section provides comprehensive documentation for the `html2rss-configs` project, which contains feed configurations for various websites. You can find a list of all available configurations in the [Feed Directory]({{ '/feed-directory/' | relative_url }}).

‎html2rss-configs/reference/ci-building.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: default
3+
title: CI Building
4+
parent: Reference
5+
grand_parent: html2rss-configs
6+
nav_order: 2
7+
---
8+
9+
# CI: Building on the CI
10+
11+
Modifying existing or adding new feed configurations will trigger the CI to fetch the feed and check for the presence of feed items.

‎html2rss-configs/reference/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: default
3+
title: Reference
4+
has_children: true
5+
parent: html2rss-configs
6+
nav_order: 3
7+
---
8+
9+
# Reference
10+
11+
This section provides detailed reference information for `html2rss-configs`.

‎html2rss-configs/reference/programmatic-usage.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
---
2+
layout: default
3+
title: Programmatic Usage
4+
parent: Reference
5+
grand_parent: html2rss-configs
6+
nav_order: 1
7+
---
8+
9+
# Programmatic Usage
10+
11+
You can use `html2rss-configs` programmatically in your Ruby applications.
12+
13+
Add to your Gemfile:
14+
15+
```ruby
16+
gem 'html2rss-configs', git: 'https://github.com/html2rss/html2rss-configs.git'
17+
```
18+
19+
Use it in your code:
20+
21+
```ruby
22+
require 'html2rss/configs'
23+
24+
config = Html2rss::Configs.find_by_name('domainname.tld/whatever')
25+
```
26+
27+
This will return the feed configuration.

‎html2rss-configs/tutorials/index.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: default
3+
title: Tutorials
4+
has_children: true
5+
parent: html2rss-configs
6+
nav_order: 1
7+
---
8+
9+
# Tutorials
10+
11+
This section provides step-by-step guides to help you get started with `html2rss-configs`.

0 commit comments

Comments
 (0)