Add docs - Githubissues

vinicvaz commented 1 month ago

This PR is adding the following:

[x] Docstrings to all methods in VAME package
[x] Typing annotation in all functions definitions in VAME package
[x] Docs app - Adding basic docusaurus app for VAME project
[x] Docs API Reference - Add VAME python API Reference in docs app.
[x] FAQ docs section

This is not the final version of the documentation app, but rather an initial iteration that defines a structure we can utilize to enhance the organization and documentation of the package

Running the docs app

Go to /docs/vame-docs-app and run

yarn
yarn start

Suggested to run using node >18

Example screenshots of docs app:

bendichter commented 1 month ago

I'd rather not commit all of the generated docs files. Is there a workflow that allows us to not commit those into the main branch?

bendichter commented 1 month ago

Could you change all docstring to use double quotes?

"""This"""

not

'''This'''

This is a PEP8 convention

bendichter commented 1 month ago

This looks great! Just a few minor points.

bendichter commented 1 month ago

Also, it would be helpful to set up a GitHub action to render a preview of the docs

bendichter commented 1 month ago

See the GitHub Action files here: https://docusaurus.io/docs/deployment#triggering-deployment-with-github-actions

luiztauffer commented 1 month ago

I'd rather not commit all of the generated docs files. Is there a workflow that allows us to not commit those into the main branch?

I think we could just generate the API Reference markdown files in the action and they'd exist in gh-pages branch. But what do we gain from that? We would loose the option to check for docs updates at PR reviews, whenever the Python API changes, for example.

vinicvaz commented 1 month ago

Also, it would be helpful to set up a GitHub action to render a preview of the docs

Hey @bendichter , here is the github page for the docs: https://ethoml.github.io/VAME/

There are few things to fix in the docs, like:

Landing page using docusaurus hero colors and features images
Remove docusaurus favicon and use a vame
Get a nice vame logo to use as navbrand
Decide if keep the blog page, if so, set the name of the authors that will write there.

But of course, this are things that we can keep improving and defining together.

vinicvaz commented 1 month ago

I'd rather not commit all of the generated docs files. Is there a workflow that allows us to not commit those into the main branch?

About this I'm not sure what would be the best approach in this case... I understand your point and honestly I also don't like the idea of having the entire docs app in the main branch since it is not part of the package, but also I'm thinking about the cycle of updating/developing the docs. Maybe an option is to have a specific docs branch called /docs to store everything, the package and the docs app, and let all the other branches ignoring the folder /docs. With this branch we can:

pr/merge main into it when package changes so the docs can be automatically generated and deployed
use the branch as base to develop docs pages and features

All the other branches would be based on main and ignore /docs folder. The only problem with this is to keep the consistency between the .gitignore files

This is just an idea, we can discuss about other options too but let me know your thoughts on that @luiztauffer @bendichter

bendichter commented 1 month ago

The website looks great! I agree with the to-do.

I see you have already created a gh-pages branch with the generated code. That's another standard approach and would be fine with me. However, the generated pages should not be edited directly. If you do that, then you'll lose all of those edits as a soon as you re-generate. If we do that then we should remove the generated files from this branch. I'd like to avoid having them in the git history of the main branch

bendichter commented 1 month ago

But either way, could you still try to put a GH Action for a docs preview together?

vinicvaz commented 1 month ago

The website looks great! I agree with the to-do.

I see you have already created a gh-pages branch with the generated code. That's another standard approach and would be fine with me. However, the generated pages should not be edited directly. If you do that, then you'll lose all of those edits as a soon as you re-generate. If we do that then we should remove the generated files from this branch. I'd like to avoid having them in the git history of the main branch

Sure, we are deploying to github pages from the gh-pages branch that is receiving the docs build files from the github workflow. I'll create a previous action to run and automatically to generate the markdown files for the api reference.

vinicvaz commented 1 month ago

But either way, could you still try to put a GH Action for a docs preview together?

sorry, what you mean by the preview? the action to test the docs build or what?

bendichter commented 1 month ago

For any PR, I want the docs to build and I want to be able to see what the new docs look like by pressing a button here

These docs describe how to do that: https://docusaurus.io/docs/deployment#triggering-deployment-with-github-actions

bendichter commented 1 month ago

Also, the GitHub link currently goes to the Docusourus GitHub. Can we change that to the VAME repo?

vinicvaz commented 1 month ago

For any PR, I want the docs to build and I want to be able to see what the new docs look like by pressing a button here

Got it but I'm not sure if it is possible using github pages only. There is a long discussion about this feature in this link and this issue. The docusaurus link you sent me is more related to a build test validation, not a preview I guess. Using external services, like vercel or others which lets us use extra servers to host the page we can create a "staging" environment for the PR preview.

I've also find this interesting repository that might help us https://github.com/rossjrw/pr-preview-action, but:

looks like it does not work on forks, the support is comming in v2
I'm not sure how it would work since it will use the same base url of the main docs but with a extra path path, ex: https://ethoml.github.io/VAME/pr-preview-action/my-new-pr . It might be accessible on the same docs url, that is not a big problem but would be better to have it in a different subdomain.

Maybe I'm missing something here but let me know what you think

bendichter commented 1 month ago

Maybe this one? https://github.com/marketplace/actions/build-deploy-to-github-pages-and-deploy-pr-preview#docusaurus

If this is hard we can skip it and come back to it later.

I like the idea of the blog. I think Steph could write a post about the paper there, and it would be a good place to highlight labs using VAME for different projects.

vinicvaz commented 1 month ago

Maybe this one? https://github.com/marketplace/actions/build-deploy-to-github-pages-and-deploy-pr-preview#docusaurus

If this is hard we can skip it and come back to it later.

I like the idea of the blog. I think Steph could write a post about the paper there, and it would be a good place to highlight labs using VAME for different projects.

this looks promising, I'll take a look, thanks!

vinicvaz commented 1 month ago

@bendichter what you think about closing this pr, deleting this branch and splitting it into two different branches, being them:

1. One with the updates for the package
1. docs branch with the package + docs app

This will ensure that we are not sending the docs app to the dev or main branches.

bendichter commented 1 month ago

sure

EthoML / VAME

Add docs #7

Running the docs app