Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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. #268

Closed
krasi-georgiev opened this issue Nov 12, 2020 · 13 comments

Comments

@krasi-georgiev
Copy link
Collaborator

@krasi-georgiev krasi-georgiev commented Nov 12, 2020

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: #194

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

@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Nov 12, 2020

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.

@krasi-georgiev krasi-georgiev changed the title Create a github book and move all miner related docs in the miner repo. 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. Nov 12, 2020
@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Nov 12, 2020

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

@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Nov 18, 2020

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 #282

@gitcoinbot
Copy link

@gitcoinbot gitcoinbot commented Nov 23, 2020

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.

@gitcoinbot
Copy link

@gitcoinbot gitcoinbot commented Nov 25, 2020

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.

@hhio618
Copy link
Contributor

@hhio618 hhio618 commented Nov 27, 2020

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!

@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Nov 27, 2020

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

@hhio618
Copy link
Contributor

@hhio618 hhio618 commented Nov 27, 2020

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

@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Nov 27, 2020

  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.

@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Nov 27, 2020

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

@hhio618
Copy link
Contributor

@hhio618 hhio618 commented Nov 28, 2020

Thanks for the tips. I just submitted another PR.

@gitcoinbot
Copy link

@gitcoinbot gitcoinbot commented Nov 30, 2020

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:


@krasi-georgiev
Copy link
Collaborator Author

@krasi-georgiev krasi-georgiev commented Dec 22, 2020

This is now done

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants