Regarding project "Refactor and Automate Infusion Documentation"

Yash Jipkate yashjipkate at gmail.com
Sun Mar 1 06:21:58 UTC 2020


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> 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>
> wrote:
>
>>
>>
>> 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>
>> 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?
>>
>>
>> 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.
>
>>
>>>    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.
>>
>>
>> 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>
> .
>
>>
>>>    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.
>>
>> 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
>>> 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
>>
>>
>>
>
> 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: <https://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20200301/79bc17c1/attachment.htm>


More information about the fluid-work mailing list