Regarding project "Refactor and Automate Infusion Documentation"

Mon Mar 2 12:57:33 UTC 2020

Hi Yash,

It isn’t required to work on those issues. However, feel free to triage them and leave comments as necessary (e.g. if they are no longer applicable and should be closed). 

Other things you could look at in preparation for your proposal would be:

The cross repo event communication you mentioned
The current structure, design, and etc.. how that might be affected by splitting things up
Other static site generators, pros/cons for using which ones

Also, regarding your comments about HUGO, if I’m understanding things correctly, HUGO’s speed benefits are at build/generation time, not necessarily when viewing the site. 

Feel free to ask other questions you may have.

Thanks
Justin

> On Mar 1, 2020, at 1:21 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
> 
> Also, the issues in the JIRA tracker you shared are very old and some don't seem to apply now. Should I be working on them?
> 
> 
> 
> 
> On Sat, Feb 29, 2020 at 5:32 PM Yash Jipkate <yashjipkate at gmail.com <mailto:yashjipkate at gmail.com>> wrote:
> Hi Justin,
> 
> Apologies for late reply, was busy with my exams, but they are gone for good now. I have addressed your comments below.
> 
> 
> On Wed, Feb 26, 2020 at 8:31 PM Justin Obara <obara.justin at gmail.com <mailto:obara.justin at gmail.com>> wrote:
> 
> 
>> On Feb 25, 2020, at 3:36 PM, Yash Jipkate <yashjipkate at gmail.com <mailto:yashjipkate at gmail.com>> wrote:
>> 
>> 
>> Hi Justin,
>> 
>> Thanks for the reply. Apologies for the late response from my side as I am in the middle of my exams. But I'll try to address as much as I can. I have left them inline.
>> 
>> On Tue, Feb 25, 2020 at 6:58 AM Justin Obara <obara.justin at gmail.com <mailto:obara.justin at gmail.com>> wrote:
>> Hi Yash,
>> 
>> Thanks for your interest in this project. I’ve left some comments inline below.
>> 
>> Thanks
>> Justin
>> 
>>> On Feb 24, 2020, at 4:29 PM, Yash Jipkate <yashjipkate at gmail.com <mailto:yashjipkate at gmail.com>> wrote:
>>> 
>>> Hi everyone,
>>> 
>>> I am Yash, and I need some discussion regarding the project "Refactor and Automating Infusion Documentation" and wanted to get your opinions on it.
>>> The HUGO code would be in a different repository; this would mean that the current repo would have to be cleaned of any rendering code, just .md and static files would remain. There is a way to clone another repo into a repo with the help of a script in the CI job.
>> Yes, ideally the content would be separate so that the Static Site Generator could be changed if needed, without the need to modify any of the content. Setting up a CI job, e.g. using GitHub Actions, could be one possible means of retrieving the content. Although this would also need to be easily testable for development so would likely involve some build task that could be run locally as well.
>> 
>> By testable, do you mean testing the code changes in the HUGO repo or the changes in the docs repo? Does the docs repo need testing?
> 
> I’d say both. For example if you make some docs changes, you’ll want to make sure that it renders correctly, and links to other pages are functioning. That might involve running an instance of the Static Site Generator locally. Actually thinking through this process would be helpful too. It may affect how we make other decisions related to this project.
> 
> So I was thinking that we could have a script for local testing of the docs repo - something like `bash run test.sh` - which would use the config files of HUGO to run a local instance of docs. We can have those config files in a tests/ folder. HUGO can be configured <https://gohugo.io/getting-started/configuration/> to look for necessary files other than at the root level. We can pull the required files directly from the remote server rendering repo and delete them or add them to .gitignore to avoid getting those in the repo.
>>> The CI should trigger whenever there is a push to main docs repo; this can be achieved by broadcasting a repository dispatch event from the main docs repo.
>> Will another GitHub repo be able to consume the “repository dispatch event”?
>> 
>> Yes, the dispatch event is a POST request sent to the repo we are targeting. 
> 
> Could you like to the docs for the dispatch event both for sending and consuming it?
> 
> You can find them here <https://developer.github.com/v3/repos/#create-a-repository-dispatch-event> and here <https://help.github.com/en/actions/reference/events-that-trigger-workflows#external-events-repository_dispatch>. 
>>> The cloning of the repo can be done tag-wise, i.e., instead of cloning the whole repo, cloning just a specific tag(s) would be done looped over all the available tags.
>> That could work. Does that actually save complexity and time over checking out the whole repo and locally iterating over tags?
>> 
>> I guess it would take slightly more time than cloning the whole repo, but HUGO doesn't have git variables that could extract tags from it, that's why I came up with this solution. 
>>> There are some libraries for indexing content and implementing the search functionality like hugo-lunr
>>> The front matter - since it is required to not include it in the files of the main docs repo - can be made as layouts. The only needed front matter seems to be the title of the page and the GitHub link - both of which can be determined with the help of FIle Variables in HUGO. 
>>> The file structure would result as follows: All the .md documentation files would be having the same organization with their tags at the topmost level. In other words, the file structure for the .md files would be content -> <tag> -> <files-in-their =-original-structure>. The static files would be placed in static/ at the same level as 'content' as required by HUGO.
>>> After cloning a tag, its contents would be copied to relevant directories, and then the clone would be deleted, and the process would be repeated for each tag, thus watching changes in each tag.
>>> These are some of my findings. What are your opinions? Should this be the way to do it? Or am I missing something that needs to be addressed? 
>> 
>> I don’t know for sure if this will work or is the best solution, but it looks like a good starting point to continue to research and test from. You can also look into other static site generators if there are others that may satisfy the requirements better.
>> 
>> Okay, I'll take a look at some other site generators as well. 
> 
> I think HUGO would be a good fit because of its extreme speed. In my opinion, a docs site should be as fast as possible since developers come there mostly when they are searching for something and no one wants a preloader to take most of their time. What do you think?
>> 
>>> 
>>> It would be great if I could get some insight into this. Also, it would be of great help if I get some guidance on how to start since the current docs repo has no standing issues on the tracker.
>> 
>> You can find more issues in the JIRA issue tracker: https://issues.fluidproject.org/browse/FLUID-6160?jql=project%20%3D%20FLUID%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)%20AND%20component%20%3D%20Website <https://issues.fluidproject.org/browse/FLUID-6160?jql=project%20=%20FLUID%20AND%20status%20in%20(Open,%20%22In%20Progress%22,%20Reopened)%20AND%20component%20=%20Website>
>> 
>> Oh, wasn't aware of this tracker, thanks for pointing out. 
>> 
>> But you should also start by making sure you can get the current site up and running locally. 
>> 
>> Do you mean using docpad? If yes, then I have already done that. 
> 
> Yes that’s what I meant. 
> 
>> 
>>> 
>>> Thanks and Regards, 
>>> Yash Jipkate
>>> Sophomore Undergraduate,
>>> IIT(BHU) Varanasi
>>> India
>>> 
>>> 
>>> _______________________________________________________
>>> fluid-work mailing list - fluid-work at lists.idrc.ocad.ca <mailto:fluid-work at lists.idrc.ocad.ca>
>>> To unsubscribe, change settings or access archives,
>>> see https://lists.idrc.ocad.ca/mailman/listinfo/fluid-work <https://lists.idrc.ocad.ca/mailman/listinfo/fluid-work>
>> 
>> 
>> Thanks and Regards, 
>> Yash Jipkate
>> Sophomore Undergraduate,
>> IIT(BHU) Varanasi
>> India
> 
> 
> 
> Thanks and Regards, 
> Yash Jipkate
> Sophomore Undergraduate,
> IIT(BHU) Varanasi
> India
> 
> Thanks and Regards, 
> Yash Jipkate
> Sophomore Undergraduate,
> IIT(BHU) Varanasi
> India
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20200302/a6050f27/attachment.html>