Telliot: Convert the docs into gitbook format and create a GH actions daily task to copy all docs from the miner repo into the main tellor docs repo.

Created on 12 Nov 2020  ·  13Comments  ·  Source: tellor-io/telliot

At the moment the miner repo has some docs under docs folder and others are kept in the main docs repo at https://github.com/tellor-io/TellorDocs. I think the main docs repo should keep docs related to the project itself and an overview of all components and miner specific docs(how to build, how to run etc) should be kept here in the miner's repo. The main docs repo will then just have a link to the miners github book docs.
This has 2 main benefits

  • when we make changes to the code in the same PR can also update the docs.
  • easier to keep in sync since there will be no need to open 2 PRs.
  • some parts of the docs can be auto-generated from the code itself: https://github.com/tellor-io/TellorMiner/issues/194

Follow the issue
A solid command of the English language is important for this issue

good first issue help wanted .high clean up

All 13 comments

On a second thought a much nicer user experience would be to keep all docs in a single github book rather then making people jump between books so to achieve this we should:

  • still keep all miner related docs here in the miner repo(easier to keep the docs in sync with the code changes)
  • create a daily GH actions cron task to copy the miner docs from here to the main tellor docs repo.

I am renaming the title to this new idea.

One very important caveat is to put a very visible note in the main tellor docs repo that for miner docs changes a PR should be open in the miner repo and not in the docs repo as otherwise the changes will be overwritten from the daily sync task.

this GH action seems to be the one to use
https://github.com/repo-sync/repo-sync

so the idea is:

  1. one PR to move all docs from https://github.com/tellor-io/TellorDocs/tree/master/miner-documentation to this repo in the /docs/miner-documentation folder.
  2. Another PR to merge the docs from /docs/miner-documentation with the existing docs in /docs and convert them into the git book format.
  3. Move the root README.md and CHANGELOG.md into the docs folder and just leave a link pointing to the gitbook.
  4. Another PR to setup repo-sync/repo-sync to sync the docs folder from this repo into https://github.com/tellor-io/TellorDocs/tree/master/miner-documentation
  5. Another PR to add notes some quite visible warnings to never edit https://github.com/tellor-io/TellorDocs/tree/master/miner-documentation directly and edit the docs in this repo instead which will be auto-synced with the main docs repo.

With this workflow, it will be quite easy to keep the docs up to date, but still provide a single website to the user to read the entire document.

This needs to be done after or together with https://github.com/tellor-io/TellorMiner/issues/282

Issue Status: 1. Open 2. Started 3. Submitted 4. Done


__This issue now has a funding of 14.0 TRB (435.58 USD @ $31.11/TRB) attached to it.__

Issue Status: 1. Open 2. Started 3. Submitted 4. Done


__Work has been started__.

These users each claimed they can complete the work by 265 years, 12 months from now.
Please review their action plans below:

1) sebastiantf has applied to start work _(Funders only: approve worker | reject worker)_.

Seems like a straightforward task with Github Actions. I shall try doing this
2) developerfred has applied to start work _(Funders only: approve worker | reject worker)_.

I'd love to do this portability, I already have experience with gitbook and I recently worked on a tellor golang issue
3) echolon166 has applied to start work _(Funders only: approve worker | reject worker)_.

I would like to assist you with this task. I will follow the explanation given by the krasi-georgiev in the issue, and will convert the docs into gitbook format & create the github actions task as you wanted.
4) manyrios has applied to start work _(Funders only: approve worker | reject worker)_.

Looks very interesting I would like to try it
5) hhio618 has been approved to start work.

Ok, seems straightforward. we can easily auto-generate some docs from the code like what Thanos did.

Learn more on the Gitcoin Issue Details page.

1. one PR to move all docs from `https://github.com/tellor-io/TellorDocs/tree/master/miner-documentation` to this repo in the `/docs/miner-documentation` folder.

2. Another PR to merge the docs from `/docs/miner-documentation` with the existing docs in `/docs` and convert them into the git book format.

Hey @krasi-georgiev. The above PR(#298) will do these.
Also, I checked repo-sync/repo-sync out. I'm afraid that is for syncing two repositories with shared commit histories. I'll submit another PR to address the folder sync we need here!

Thanks, what do you have in mind for the auto sync?

I'm testing this GitHub action aproach right now:
Every 1 hour:
1. Clone https://github.com/tellor-io/telliot
2. Compare TellorDocs/miner-documentation folder with telliot/docs using md5 hashes.
3. If any differences then -> update TellorDocs/miner-documentation
4. Push changes to TellorDocs repo

  1. Push changes to TellorDocs repo

Instead of a direct push we just want the tool to open a PR so we can see the changes and will manually approve and merge.

btw I just remembered that a college did this script for a similar thing so maybe you can adopt some of the logic from there.
https://github.com/prometheus/prometheus/blob/master/scripts/sync_repo_files.sh

Thanks for the tips. I just submitted another PR.

Issue Status: 1. Open 2. Started 3. Submitted 4. Done


__Work for 14.0 TRB (361.72 USD @ $25.84/TRB) has been submitted by__:


This is now done

Was this page helpful?
0 / 5 - 0 ratings

Related issues

krasi-georgiev picture krasi-georgiev  ·  15Comments

krasi-georgiev picture krasi-georgiev  ·  9Comments

andrewsmedina picture andrewsmedina  ·  11Comments

AaronFriel picture AaronFriel  ·  206Comments

xaprb picture xaprb  ·  25Comments