Regarding project "Refactor and Automate Infusion Documentation"

Tue Feb 25 20:36:33 UTC 2020

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> 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> 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.
>
>    1. 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?

>
>    1. 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.

>
>    1. 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.

>
>    1. There are some libraries for indexing content and implementing the
>    search functionality like hugo-lunr
>    2. 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.
>    3. 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.
>    4. 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.

>
>
> Thanks and Regards,
> Yash Jipkate
> Sophomore Undergraduate,
> IIT(BHU) Varanasi
> India
>
> _______________________________________________________
> fluid-work mailing list - fluid-work at lists.idrc.ocad.ca
> To unsubscribe, change settings or access archives,
> see 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/c459a1d0/attachment.html>