Regarding project "Refactor and Automate Infusion Documentation"

Wed Feb 26 15:01:34 UTC 2020

> On Feb 25, 2020, at 3:36 PM, Yash Jipkate <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.
>> 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?
>> 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. 
> 
>> 
>> 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

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