Codecov Report

Merging #226 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #226   +/-   ##
=======================================
  Coverage   96.66%   96.66%           
=======================================
  Files          16       16           
  Lines        1499     1499           
=======================================
  Hits         1449     1449           
  Misses         50       50           

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update fc8a8e9...2ff6b68. Read the comment docs.

@mstruebing thanks for the review. 🚀

The answer to both questions is yes, but we can do that only after this PR merged.

After merge you can follow this guide.

But we could already integrate in into our github actions to always have the latest version, right?
If you need help how to do it feel free to ask :)

I'm not sure if it's really necessary, I think that just configuring the github pages section in the settings is enough to always have the latest version.
What do you think?

I think: you've committed the current readme after processing it with docsify. If we change the readme, we manually need to commit changes with docsify to the docs folder. That won't get triggered automatically.
My imagination is: we change something on the readme and after it get's pushed to master a CI job starts running to generate the new docsify version and commits itself to the docs folder.

Or am I wrong? If so, sorry for bothering you.

I didn't change the current README. I have created the docs folder with some markdown files. After this PR mergerd into master and github pages configured as following this guide every push to master will be processed and hosted automatically by github.

At least every time I used docsify it worked like this.

If it doesn't work, I can think about another way to host it. What do you think?

I didn't change the current README. I have created the docs folder with some markdown files. After this PR mergerd into master and github pages configured as following this guide every push to master will be processed and hosted automatically by github.

At least every time I used docsify it worked like this.

If it doesn't work, I can think about another way to host it. What do you think?

Thank you for your PR! 🔥

But I am concerned about the same question that @mstruebing asked.
In fact, I'm not sure I understand you. The docsify-сli init command is used to create the documentation, right?
In this case, the next time someone changes README.md, we will have to run it manually to update the content.

Deploy really automatic, but the question is about generating docs
Correct if I'm wrong :)

Correct, that's exactly what I've meant. :)

I didn't change the current README. I have created the docs folder with some markdown files. After this PR mergerd into master and github pages configured as following this guide every push to master will be processed and hosted automatically by github.
At least every time I used docsify it worked like this.
If it doesn't work, I can think about another way to host it. What do you think?

Thank you for your PR! fire

But I am concerned about the same question that @mstruebing asked.
In fact, I'm not sure I understand you. The docsify-сli init command is used to create the documentation, right?
In this case, the next time someone changes README.md, we will have to run it manually to update the content.

Deploy really automatic, but the question is about generating docs
Correct if I'm wrong :)

Thanks for your review 🚀

The documentation is generated at runtime, so when you run the docsify serve command the documentation is generated again. This command is executed by integrating with github.

@DDtKey @mstruebing Were the questions answered? 😬

Sorry for this mess.

I didn't change the current README. I have created the docs folder with some markdown files. After this PR mergerd into master and github pages configured as following this guide every push to master will be processed and hosted automatically by github.
At least every time I used docsify it worked like this.
If it doesn't work, I can think about another way to host it. What do you think?

Thank you for your PR! fire
But I am concerned about the same question that @mstruebing asked.
In fact, I'm not sure I understand you. The docsify-сli init command is used to create the documentation, right?
In this case, the next time someone changes README.md, we will have to run it manually to update the content.
Deploy really automatic, but the question is about generating docs
Correct if I'm wrong :)

Thanks for your review rocket

The documentation is generated at runtime, so when you run the docsify serve command the documentation is generated again. This command is executed by integrating with github.

@DDtKey @mstruebing Were the questions answered? grimacing

Sorry for this mess.

Thanks for the answer!

Actually, this is really confusing, since serve should only start the server based on the ./docs folder. After all, I can make changes to the documentation manually, otherwise it makes no sense to store docs in the version control system (you could just generate them on the fly and host in that case without storing them in the git).

This behavior contradicts the description of serve.
I checked locally and without init, the documentation was not generated automatically.

Perhaps I still don’t understand something in integration with github 😞

I didn't change the current README. I have created the docs folder with some markdown files. After this PR mergerd into master and github pages configured as following this guide every push to master will be processed and hosted automatically by github.
At least every time I used docsify it worked like this.
If it doesn't work, I can think about another way to host it. What do you think?

Thank you for your PR! fire
But I am concerned about the same question that @mstruebing asked.
In fact, I'm not sure I understand you. The docsify-сli init command is used to create the documentation, right?
In this case, the next time someone changes README.md, we will have to run it manually to update the content.
Deploy really automatic, but the question is about generating docs
Correct if I'm wrong :)

Thanks for your review rocket
The documentation is generated at runtime, so when you run the docsify serve command the documentation is generated again. This command is executed by integrating with github.
@DDtKey @mstruebing Were the questions answered? grimacing
Sorry for this mess.

Thanks for the answer!

Actually, this is really confusing, since serve should only start the server based on the ./docs folder. After all, I can make changes to the documentation manually, otherwise it makes no sense to store docs in the version control system (you could just generate them on the fly and host in that case without storing them in the git).

This behavior contradicts the description of serve.
I checked locally and without init, the documentation was not generated automatically.

Perhaps I still don’t understand something in integration with github disappointed

The init command is used as bootstrap. Try to run init command and then run the serve command. After the first init, you can just run the serve command and the docs will up.

Github pages integration will watch the docs folder and every push to master will rerun the serve command. It's a little bit magic, but it works. I did it in my fork. You can check it out here the result.

In my fork, I just merged my branch into master and followed the steps in the docsify documentation

@DDtKey My mind blown at the first time I saw that. 🧙

The init command is used as bootstrap. Try to run init command and then run the serve command. After the first init, you can just run the serve command and the docs will up.

Github pages integration will watch the docs folder and every push to master will rerun the serve command. It's a little bit magic, but it works. I did it in my fork. You can check it out here the result.

In my fork, I just merged my branch into master and followed the steps in the docsify documentation

@DDtKey My mind blown at the first time I saw that. mage

Hmm, no, after every change of README.md(in the root folder, not in the docs) I have to start the init again.
The serve simply starts the server with the contents of the ./docs and no more.

I understand that the serve is started by the github, but it is the init that generates the contents of the docs folder.

This is not very similar to the correct behavior without the participation of users, because then the github would have to overwrite the folder automatically, which really contradicts.

I believe this should be built on top of CI workflow. It gives control.
In any case, I have already seen the documentation itself, and it looks amazing! 🚀

The init command is used as bootstrap. Try to run init command and then run the serve command. After the first init, you can just run the serve command and the docs will up.
Github pages integration will watch the docs folder and every push to master will rerun the serve command. It's a little bit magic, but it works. I did it in my fork. You can check it out here the result.
In my fork, I just merged my branch into master and followed the steps in the docsify documentation
@DDtKey My mind blown at the first time I saw that. mage

Hmm, no, after every change of README.md(in the root folder, not in the docs) I have to start the init again.
The serve simply starts the server with the contents of the ./docs and no more.

I understand that the serve is started by the github, but it is the init that generates the contents of the docs folder.

This is not very similar to the correct behavior without the participation of users, because then the github would have to overwrite the folder automatically, which really contradicts.

I believe this should be built on top of CI workflow. It gives control.
In any case, I have already seen the documentation itself, and it looks amazing! rocket

@DDtKey now I got your point. With the ./docs folder, Is it necessary keep the README.md in the root folder with the whole documentation?

I think about to change the README.md in the root path to keep only the minimal information (logo, badges, etc) and keep inside the ./docs everything else to be hosted. In that case, README.md would no longer be changed, but the files inside the ./docs folder.

I have a couple of questions:

1. As I understood the docs folder we should maintain manually. Am I right?
2. If so, we should decide it's okay for us or not?
3. Some pages look not so good. Can we improve them?

@DDtKey @mstruebing What do you think?

I have a couple of questions:

1. As I understood the `docs` folder we should maintain manually. Am I right?

2. If so, we should decide it's okay for us or not?

3. Some pages look not so good. Can we improve them?

@mgrachev Thanks for your review 🚀

1. Yes. Instead of maintaining a huge README.md in the root folder, the docs folder will be maintained
2. Yes, I think.
3. Yes, of course. I just moved the README.md content into the docs folder and split it into some files

@mgrachev do you suggest using bold text for wrong and correct sections?

@mgrachev do you suggest using bold text for wrong and correct sections?

I like examples from README.md. Can we do something like that?

@mgrachev do you suggest using bold text for wrong and correct sections?

I like examples from README.md. Can we do something like that?

@mgrachev Sure. What do you think?

@mgrachev Sure. What do you think?

👍

Can you update all examples this way?

@mgrachev Sure. What do you think?

+1

Can you update all examples this way?

@mgrachev it's done. You can check it out here

@mgrachev

2. If so, we should decide it's okay for us or not? 

Duplicating information is really not very convenient.

We can do as suggested by @wesleimp above, leaving in README only basic information, such as a short description and a menu with links to documentation.

But it would not be a bad decision to maintain the documentation manually, and build the README.md by inserting files from it (i.e. go from the opposite), something like that:

include ./docs/intoduction.md
include ./docs/quick_start.md
...

But unfortunately the github does not allow this.
Perhaps there are similar solutions that will help with this, let's say with each push to master will update a README in the root folder.

We can do as suggested by @wesleimp above, leaving in README only basic information, such as a short description and a menu with links to documentation.

I like this idea 🙂

@mstruebing @DDtKey What do you think about it?

I like this too! :) Looks good, thank you

@wesleimp Thank you for your contribution! 👍