Regarding project "Refactor and Automate Infusion Documentation"

Yash Jipkate yashjipkate at gmail.com
Tue Mar 10 19:05:26 UTC 2020


Hi Justin,

Responded inline.

Thanks.
Yash


On Tue, Mar 10, 2020 at 9:52 PM Justin Obara <obara.justin at gmail.com> wrote:

> Hi Yash,
>
> Comments below.
>
> Thanks
> Justin
>
> On Mar 10, 2020, at 11:40 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>
> Seems like the previous mail got sent in plain text mode. Therefore, the
> hyperlinks vanished. I am sharing the links below.
>
>
>    - Archetypes in HUGO <https://gohugo.io/content-management/archetypes/>
>    - Angular <https://angular.io/docs> and React
>    <https://reactjs.org/docs/getting-started.html> docs
>    - Static file management in HUGO
>    <https://gohugo.io/content-management/static-files/>
>
>
> Thanks.
> Yash
>
>
> On Tue, Mar 10, 2020 at 8:57 PM Yash Jipkate <yashjipkate at gmail.com>
> wrote:
>
>> Hi Justin,
>>
>> I have left some comments inline. Also, I'll be sharing the draft
>> proposal soon.
>>
>> Thanks.
>> Yash
>>
>>
>> On Tue, Mar 10, 2020 at 5:37 PM Justin Obara <obara.justin at gmail.com>
>> wrote:
>> >
>> > Hi Yash,
>> >
>> > I’ve left some more comments below.
>> >
>> > Thanks
>> > Justin
>> >
>> > On Mar 10, 2020, at 2:21 AM, Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >
>> > Hi Justin,
>> >
>> > Thanks for the reply. I have responded inline.
>> >
>> > Also, since the student application period approaches, should I start
>> on my draft proposal using HUGO as the SSG? Since I have found it as the
>> best alternative till now. If we find any other better alternative, then we
>> can switch. But according to me, HUGO is best suited for our needs.
>> >
>> >
>> > This would be up to you. You’re welcome to propose what you think is
>> best. You might want to consider adding steps for investigation,
>> experimentation and leaving things open to change.
>> >
>> >
>> > Thanks.
>> > Yash
>> >
>> >
>> > On Tue, Mar 10, 2020 at 4:26 AM Justin Obara <obara.justin at gmail.com>
>> wrote:
>> >>
>> >> Hi Yash,
>> >>
>> >> Some comments inline below.
>> >>
>> >> Thanks
>> >> Justin
>> >>
>> >> On Mar 9, 2020, at 4:32 PM, Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >>
>> >> Hi Justin,
>> >>
>> >> Thanks for the reply. I have responded inline.
>> >>
>> >> Thanks
>> >> Yash
>> >>
>> >>
>> >> On Mon, Mar 9, 2020 at 6:51 PM Justin Obara <obara.justin at gmail.com>
>> wrote:
>> >>>
>> >>> Hi Yash,
>> >>>
>> >>> Somewhere along the line we lost our CC to the fluid-work mailing
>> list. I’ve added that back in now so that others can follow along and
>> provide input as needed.
>> >>>
>> >>> Another tool to look at would be https://docusaurus.io. It would be
>> good to also investigate if there are other options/solutions that we
>> haven’t yet mentioned.
>> >>
>> >>
>> >> A complete list of all the major static site generators can be found
>> at StaticGen. The list is sorted on the basis of recent trends in the
>> community. Regarding Docusaurus, I found this blog that compares HUGO and
>> Docusaurus. There is also this comment in an issue that compares Jekyll,
>> Docusaurus, and HUGO. I read the Docusaurus docs and there are some
>> advantages that it provides over the other SSGs.
>> >>
>> >> In-built versioning
>> >> Translations
>> >> Inbuilt search feature using Algolia.
>> >>
>> >> To summarize all the findings over the course of this thread, the
>> various SSGs and their details are:
>> >>
>> >> HUGO
>> >>
>> >> Written in Go, therefore fast build times - countered by the fact that
>> Go deprives us of npm packages and build times are not that big a concern
>> to us.
>> >> The search functionality needs to be manually implemented by the ways
>> described here.
>> >> Versioning can be realized by the usage of tags - inbuilt provision
>> for tag-specific pages.
>> >> Various themes to choose from, all cost-free.
>> >> Pre-defined convention for best practices.
>> >> Vast community support and one of the trending SSGs (according to
>> stars on the repo in the past week: source)
>> >>
>> >> 11ty
>> >>
>> >> Written in JS, access to npm packages.
>> >> No search functionality provided nor any documentation provided on how
>> to implement it. Its docs site uses Duck Duck Go search.
>> >> Versioning can be done by collections but not as intuitive as HUGO
>> tags - no tag-specific pages.
>> >> No provision for custom themes, need to start from scratch. Although
>> many third-party themes are available. No documentation on using a custom
>> theme as in HUGO.
>> >> Flexible in terms of conventions.
>> >> Good community support.
>> >>
>> >> Docusaurus
>> >>
>> >> Written in JS, access to npm packages.
>> >> In-built search functionality powered by Algolia.
>> >> In-built versioning functionality.
>> >> Only one theme available needs to be customized to change. Uses React.
>> >> Rigid conventions. Uses React components to render and therefore can
>> not modify much in its default way of rendering.
>> >>
>> >> Absence of page-level variables, and therefore would cause
>> difficulties when the SSG metadata is not allowed in the MD files. Not
>> suited for our use case.
>> >>
>> >> Good community support, backed by Facebook.
>> >>
>> >> Clearly, we can't use Docusaurus. I took a look at Hexo and it had
>> similar problems and has weak documentation. Similar goes for Docsify too.
>> It doesn't have variables and weak templating and I also found its
>> documentation less friendly. It can't be used for our requirements.
>> >>
>> >> This again puts me in favor of HUGO.
>> >>
>> >> Do you have any other suggestions?
>> >>
>> >>
>> >> Thanks for the research, feel free to look at others or other setups
>> that may inspire implementation.
>> >>
>> >>
>> >>>
>> >>> I’ve left some more comments below.
>> >>>
>> >>> Thanks
>> >>> Justin
>> >>>
>> >>> On Mar 8, 2020, at 1:16 AM, Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >>>
>> >>> Hi Justin,
>> >>>
>> >>> I just got a reply from the 11ty team on the issue that I opened.
>> 11ty has directory specific data files that can be used to define config to
>> be shared to all the lower levels. The major downside of this is that the
>> directory specific data file needs to be placed in the directory itself.
>> Therefore, the data file will be directly in between the content files.
>> >>>
>> >>>
>> >>> You say that the data file can define configuration that can be
>> shared by lower levels. So you could have two levels of directories, one
>> that contains the data file and a directory of all the docs. In that way
>> you wouldn’t haven’t worry about mixing them together. But I’d have to see
>> how this looks in a more concrete example.
>> >>
>> >>
>> >> If I am getting it the right way, you are planning to have a single
>> data file. Yes, that would then nullify the point since we won't be
>> concerned with the mixing of just one data file. But in case of multiple
>> data files, say we want to customize some folders that should be different
>> from the other folders at the same level, then we would need different data
>> files in both the folders, and that's the kind of mixing that I'm concerned
>> with.
>> >>
>> >>
>> >> I was suggesting something like
>> >>
>> >> - Tutorials/
>> >> - data file
>> >> - pages/
>> >> - tutorial_example.md
>> >> - API
>> >> - data file
>> >> - pages/
>> >> - framework_api.md
>> >>
>> >> I’m not exactly sure what our needs would be in terms of configuration
>> in these files, do we actually need one per document file, one per section,
>> or just one overall. The above example assumes one per section.
>> >
>> >
>> > Currently, we would need one configuration file per version. There are
>> three things that would be different on each page - the title, GitHub edit
>> link, and the version. This information would be normally provided via the
>> front-matter of the page but in our case, this can be provided in a data
>> file (or a shared template). The title and the GitHub link can be generated
>> from the name of the file using a variable but the version needs to be
>> provided as a tag. So this tag would need to be in the data file (or the
>> shared template) of the directory that houses it. This means that there
>> would be one data file per version and a global data file.
>> >
>> > The structure you laid out also does some mixing. The data file is
>> inside the contents folder which would contain all the MD files. In HUGO
>> this data file is totally outside of the contents folder. While this
>> doesn't have any significant performance effects, it is mainly a
>> convention-related issue. Because we would then be cloning the repo
>> 'tagwise' inside these folders. So do we want the cloned part directly in
>> between the SSG data files or do we want these two in separate folders, is
>> a matter of convention and developer ease. I would personally prefer having
>> these two separate. What is your take on this?
>> >
>> >
>> > I guess this all depends on what the directory structure looks like in
>> the SSG. It seems we might have directories for each tag/version and the
>> file could be in there, or possibly we might b able to source the
>> tag/version name from the path that the files are in.
>>
>>
>> I favor the tag-wise directory structure since that would help in
>> setting archetypes. I am not sure what do you mean by sourcing the tag
>> name, we would still need to clone tag-wise to detect the tag/version
>> name from the path, right? In that case, archetypes would do the
>> trick.
>>
>
> Maybe we’re talking about different things, I’ll wait to see what it looks
> like in your proposal.
>
> >
>> >
>> > Now that you mention the GitHub edit link, I don’t think tags are going
>> to work. The tag is frozen, so to speak. We may need to use branches
>> instead, or a combination of branches and tags. I don’t think it will
>> change your workflow much, or at all, though.
>>
>>
>> Yes, the tags are frozen, thanks for pointing that out. However, the
>> tags and branches are inconsistent. The branches are 1.9.x, 2.x.x, and
>> master, whereas the tags are v2.0.0 and v1.5.0. Also, would it be
>> sensible to have a GitHub edit link for older versions? I saw the
>> documentation for Angular and React, and both of them have their
>> documentation for older versions snapshotted and do not edit them. The
>> edit on GitHub button on the older versions' docs are either dead or
>> point to the current branch of the docs. Therefore, I suggest that we
>> follow the tag-wise classification since that is the most widely
>> accepted format. What do you think?
>>
>
> That’s an options, although I’d prefer not to have the link than to have a
> dead one. It would be nice to be able to change the documentation after the
> fact in case there was an error, typo, or missing information. I’m not sure
> how likely that is though.
>
> >
>> >
>> >>
>> >>>
>> >>> According to my plan, the content repo was to be cloned in the SSG
>> repo, so if 11ty is to be used then after the cloning we would need to
>> further copy the directory specific data files into respective folders to
>> make them useful.
>> >>>
>> >>>
>> >>> I guess this should be counted as a downside for 11ty since this
>> extra copying operation would require an extra script to maintain and would
>> cause a closer coupling.
>> >>>
>> >>>
>> >>> You’d still need some sort of script to do the cloning, so not sure
>> how much extra work it would be. Maybe I’m forgetting or missing something
>> with how you were planning to do the clone.
>> >>
>> >>
>> >> Ideally, there should be one script for one functionality, so
>> therefore I was thinking of a different script. And moreover, by a script,
>> I meant by the code - maintaining it would be an additional task
>> irrespective of whether it is in a separate file or not. Since it couples
>> the two repos very closely, the maintenance can be frequent. And yes,
>> cloning would be done through a script.
>> >>
>> >>
>> >> I think we talked about possibly having a config file in the document
>> repo that defined the parts or organization. It could also be that they are
>> organized in a specific way, example directories to categorize the
>> contents. We’d just need to know how to parse or place these directories
>> and not each individual file. In this case there is a contract on what the
>> incoming directory structure is, or instructions on how to move from one to
>> another. Something to think about.
>> >
>> >
>> > I thought that we wanted to separate all SSG related data from the
>> content repo - that would include the config file as well. And yes, we just
>> need to decide on the directory structure and the content would be placed
>> accordingly and the SSG can then render the content.
>> >
>> >
>> > The config file I meant here is something that would define the
>> structure of the content repo. The SSG repo would use this to know what
>> parts are what. It wouldn’t be something particular to a specific SSG,
>> there would need to be something in the SSG repo that translated it to it’s
>> own information. But having a consistent directory structure could possibly
>> be used in place of such a file.
>>
>>
>> The structure of the content repo would be determined by the way the
>> data files (archetypes) are stored. The directory hierarchy of the doc
>> files would be the same as I pointed out, and the other files would be
>> re-organized. I don't think there is a feature such as a config to
>> determine the directory structure. The directory structure needs to be
>> consistent with the config of the SSG because the theme and the
>> archetypes will be valid on a content structure that is similar to
>> itself. Please correct me if I got you wrong.
>>
>
> What I mean is that you’d have some document in the content repo that
> identifies it’s structure. The SSG repo, on importing in the content would
> use this to place the files in the locations that the SSG is
> expecting/needs them to be.
>

The SSG does not identify the structure of the contents, it would validate
the structure against the structure it is provided by the combination of
templates and archetypes. If it finds a different structure, then it won't
apply the templates. We can think of it as CSS selectors. Say we have two
CSS selectors as '.body .div .p'  and '.body .div' and suppose we have a
<h1> inside <body><div> then we don't have a CSS selector for '.body .div
.h1'  so it won't give any errors but it would simply apply '.body .div'
properties to it. And so the directory structure would need to be
consistent between the two repos.

>
>
> >
>> > The directory structure of the contents (src/documents) need not be
>> changed except for the images directory which would be moved to the static/
>> or as a page resource if it needs some processing (one more point where
>> HUGO beats 11ty since 11ty doesn't have any image processing features).
>> >
>> > We want the documentation to be readable/previewable on GitHub. That
>> means that the URLs (e.g. links between documents, images, etc) would need
>> to work both on GitHub and in the SSG created site. This may involve some
>> translation of these URLs. In the current site we do some of this
>> translation for changing between .md and .html, for example.
>>
>>
>> The images which don't need preprocessing (like resizing) can be
>> served directly from the static directory by relative paths and
>> through server URLs (docs). The relative path method doesn't give
>> previews in GitHub, whereas the URL method should give since that
>> doesn't have to do anything with the content management system of
>> HUGO.
>>
>
> I’m not sure what you mean here, or at least I’m not sure how this
> addresses the issue of URLs working on both GitHub and the final site.
>

Actually, if you follow the relative path method (i.e. if the image is in
static/images/image1.png then the relative path in HUGO would be
/images/image1.png) it would work correctly when HUGO renders it in HTML
but won't be available in GitHub preview. Whereas if you use the full URL
(i.e. https://<root-url>/images/image1.png) then we can see the correct
GitHub preview as well. The only condition is that the image needs to
already hosted on the server so that it can be tested in local development
because HUGO generates such URLs for all static files. Here I'm talking in
the context of the syntax of displaying an image in Markdown i.e.
![alt-text](img-url/path).

>
> >
>> > The layout file in the layouts folder would be replaced by a template
>> layout file that is provided by the SSG. In the case of HUGO, this can be
>> achieved through themes, partials, and templates
>> > The static folder would be placed in static/ in the project root.
>> > I am not clear about what is the purpose of the ghpages-files
>> directory. In the deploy section of the README, it says that we don't use
>> GitHub pages to host. Then what is the use of this directory? Also, what
>> service do we currently use to host the site?
>> >
>> > There is some legacy in that we had originally used ghpages to host the
>> site, but moved to self hosting. We may move to a hosting service at some
>> point (e.g. back to ghpages, netlify, etc.). We should investigate removing
>> the ghpages-files directory.
>> >
>> >
>> >>
>> >>>
>> >>>
>> >>> I am still inclined to HUGO because of our use case. Lesser coupling,
>> faster build times (since there are multiple steps like dispatch and
>> cloning and that would add to the build time) and a file structure
>> convention are some features that outperform 11ty. Some star features of
>> 11ty like multiple templates are not required by us since we use only MD
>> files.
>> >>>
>> >>> What do you think?
>> >>>
>> >>>
>> >>> Addressing some of the comments/questions from earlier in the thread.
>> Not sure what the issue about Hugo being written in Go. Could you explain
>> and expand on that one more.
>> >>
>> >>
>> >> Being built in Go means it is deprived of the amazing features of JS.
>> Most importantly, the features of node and NPM which have many useful
>> packages. This has been the main concern of many developers.
>> >>>
>> >>>
>> >>> Regarding flexibility. That’s not necessarily a bad thing. If we
>> maintain consistency in our use and follow best practices, I don’t think it
>> should be a matter for us and could mean that we can tailor it to our own
>> needs. If you know of a specific issue that 11ty’s flexibility is causing,
>> or could cause, it would be good to discuss it more.
>> >>
>> >>
>> >> If we are sure of maintaining best practices then this won't be much
>> of a problem. Actually, this was the case of AngularJS - it didn't have a
>> 'conventional' way of doing things and this resulted in a number of bad
>> practices. The new Angular then removed this by introducing a less flexible
>> framework. We can overcome this by setting up our own conventions that
>> would eliminate any bad practices that might pop up.
>> >>
>> >>
>> >> A contributing guide and documentation on usage, best practices,
>> conventions and etc. should be included with the project.
>> >
>> >
>> > Yes, that would be very important in deciding and cementing the
>> conventions.
>> >>
>> >>
>> >>>
>> >>>
>> >>> Thanks
>> >>> Yash
>> >>>
>> >>> On Sat, Mar 7, 2020 at 11:59 PM Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >>>>
>> >>>>
>> >>>> Hi Justin,
>> >>>>
>> >>>> I looked up 11ty more and found the following advantages over HUGO:
>> >>>>
>> >>>> 11ty (2017) is newer than HUGO (2013).
>> >>>> 11ty is built using JavaScript whereas HUGO is built using Go. JS
>> being a native web language won't ever lose support whereas Go being a
>> third party might lose support.
>> >>>> 11ty has more flexibility regarding file extensions. It works with
>> formats other than MD as well.
>> >>>> 11ty has a flexible file system. So we can build it right from the
>> current file structure.
>> >>>> I also liked the documentation of 11ty compared to the one by HUGO.
>> >>>>
>> >>>> But there is a major downside that since 11ty uses a flexible
>> directory structure, every page needs to have a front matter that specifies
>> the template it needs to use. HUGO being strict about directory structure
>> automates this process and is useful when we want to separate the content
>> from the front matter.
>> >>>>
>> >>>> I found this issue to fulfill our use case but it was closed with a
>> note stating it was solved in a version but I couldn't find any
>> documentation regarding it. Therefore I opened an 'education' type issue to
>> get their response.
>> >>>>
>> >>>> If this issue persists, then we might not be able to use 11ty for
>> our purpose.
>> >>>>
>> >>>> Thanks
>> >>>> Yash
>> >>>>
>> >>>> On Sat, Mar 7, 2020 at 12:28 AM Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >>>>>
>> >>>>> Hi Justin,
>> >>>>>
>> >>>>> Thanks for the reply. I have responded inline.
>> >>>>>
>> >>>>> Thanks.
>> >>>>> Yash
>> >>>>>
>> >>>>> On Thu, 5 Mar 2020, 7:02 pm Justin Obara, <obara.justin at gmail.com>
>> wrote:
>> >>>>>>
>> >>>>>> Hello Yash,
>> >>>>>>
>> >>>>>> Please see comments inline below.
>> >>>>>>
>> >>>>>> Thanks
>> >>>>>> Justin
>> >>>>>>
>> >>>>>> On Mar 5, 2020, at 2:43 AM, Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >>>>>>
>> >>>>>> Hi Justin,
>> >>>>>>
>> >>>>>> Just confirming whether you got my previous email. Is there
>> something I should add or elaborate on?
>> >>>>>>
>> >>>>>> Thanks
>> >>>>>> Yash
>> >>>>>>
>> >>>>>>
>> >>>>>> On Tue, Mar 3, 2020 at 3:14 AM Yash Jipkate <yashjipkate at gmail.com>
>> wrote:
>> >>>>>>>
>> >>>>>>> Hi Justin,
>> >>>>>>>
>> >>>>>>> I will try to mark the issues on JIRA since it should have only
>> legitimate issues.
>> >>>>>>> Also, I tried out the repository communication. I created a
>> dispatcher repo and added a workflow to send a dispatch to another consumer
>> repo created by me. It worked perfectly and the repo was consuming the
>> event.
>> >>>>>>
>> >>>>>> How is the consumer repo affected by forks of the dispatcher repo.
>> That is, if I fork your dispatcher repo and push to it, will it send a
>> dispatch event to your consumer repo and trigger an action?
>> >>>>>>
>> >>>>>> It’s also worth investigating other methods that do not couple the
>> repos together so closely.
>> >>>>>
>> >>>>>
>> >>>>> No, the dispatch event does not work on forks. I forked the
>> dispatcher repo here and pushed to the main branch. This failed to trigger
>> the workflow in the main consumer repo (you can check here). Also forking
>> the consumer repo won't have any downside since the dispatch event demands
>> the name of the repo along with the owner so forks won't be affected.
>> >>>>>
>> >>>>> Another method I initially thought before discovering repo
>> dispatches was to have a special server for the sole purpose of sending and
>> receiving events that would trigger builds. This would allow us to have
>> custom features not limited by those offered by GitHub API. The downside is
>> that we would need to maintain an additional repo and would not be able to
>> access the community help that exists for GitHub's API. Also since out
>> needs are satisfied by the GitHub's API, we won't need any other custom
>> features than the ones already present.
>> >>>>>>>
>> >>>>>>> I think the design would not undergo much change. I saw the
>> official documentation page of HUGO and they use pretty much similar design
>> - a top nav, a side nav, and the main content.
>> >>>>>>>
>> >>>>>>> The source code is open-sourced here. I looked at the code and
>> saw that the menu bar items were hard-coded in a site-wide config file
>> here. The layout for the menu bars are placed in partials/ of the theme
>> that HUGO's site uses.
>> >>>>>>> To maintain the design of the current site, we would have to make
>> a custom theme of our own (similar to the theme used by HUGO docs).
>> >>>>>>> The structure of the files would also need to be changed
>> accordingly. The md files or the content files would be put under content/
>> and assets under static/.
>> >>>>>>>
>> >>>>>>> The repo would be essentially HUGO-oriented, with all the folder
>> structure conforming to the one required by HUGO. In case of switching to
>> another SSG, we would need to follow the folder structure and the
>> conventional best practices followed by that particular SSG. We would again
>> need a restructuring, although not this massive. Also, things like menu bar
>> items which would be in the root config of HUGO would also be needed to
>> migrate since the new SSG might have a different approach.
>> >>>>>>
>> >>>>>> Regarding the folder structure, couldn’t we just copy/import the
>> content to whichever location we wanted during that step of the workflow.
>> Do we have to mirror it in the content repo?
>> >>>>>
>> >>>>>
>> >>>>> Yes, that's exactly what I am proposing. I plan to re-organize the
>> folder structure and not mirror the current content to the new structure.
>> >>>>>>>
>> >>>>>>> Splitting the docs and the HUGO code would deprive of the many
>> useful and core features of the tech. The front-matter or the meta-data per
>> page is of great use and can be used to greatly customize and control the
>> pages. Stripping HUGO of such important features could become a problem in
>> the future or even during this project. For example, the GitHub link to
>> edit the page is different on every page and can be stored in front-matter.
>> Also, if we wanted to add an 'author' or 'last updated' information to the
>> page, It would again be a front-matter thing.
>> >>>>>>
>> >>>>>> Can this information be automatically generated on import of the
>> content?
>> >>>>>
>> >>>>>
>> >>>>> We can have a common front matter template for all files in a
>> directory by the archetype feature of HUGO.
>> >>>>>>>
>> >>>>>>> Also, in case of switching SSG, the main part i.e. the MD doc
>> files would be in the same hierarchy of contents. The only change that
>> mostly happens in the names of the directories and some best practice
>> conventions. Therefore, in my opinion, we should not split the codebase
>> since it would be almost equal work switching in both cases but the
>> one-repo approach gives many more additional features, and this advantage
>> would be in other SSGs too.
>> >>>>>>> I took a look at some other SSGs like Jekyll and 11ty. Most of my
>> findings were the same as those by Sachin. One of the main drawbacks of
>> Jekyll is build time increases exponentially with increase in repo size.
>> 11ty has somewhat less community support.
>> >>>>>>>
>> >>>>>>> For choosing an SSG, the choice should be between Jekyll and
>> HUGO. Jekyll has a somewhat rigid structure whereas HUGO is flexible. I
>> would recommend HUGO for the task.
>> >>>>>>
>> >>>>>>
>> >>>>>> Could you explain more about your recommendations, in particular
>> against 11ty. Also, did you look at any others besides these three?
>> >>>>>
>> >>>>>
>> >>>>> I looked at Gatsby and Gridsome - the two other main SSGs - but
>> they are framework dependent i.e. on React and Vue respectively and can be
>> difficult for those who haven't worked in that area. SSGs like 11ty and
>> HUGO are easy to learn and setup.
>> >>>>>
>> >>>>> Right now, 11ty has lesser community support than HUGO. One pro of
>> using 11ty is that it can be configured to run in the current directory
>> structure. Although this can be tempting at first, in my personal
>> experience, too much flexibility causes a lack of convention and leads to
>> bad practices. This has been the case of AngularJS which being too flexible
>> gave way to randomness in conventions. One other advantage is that it can
>> handle more than just md files, but since all our documentation is in md
>> format, this isn't of much concern.
>> >>>>>
>> >>>>> Therefore I would recommend HUGO. However, I will try to research
>> more on this topic and will update you if I find HUGO outperformed by
>> another SSG.
>> >>>>>>
>> >>>>>>
>> >>>>>>>
>> >>>>>>> What are your opinions on this?
>> >>>>>>>
>> >>>>>>> On Mon, Mar 2, 2020 at 6:27 PM Justin Obara <
>> obara.justin at gmail.com> wrote:
>> >>>>>>>>
>> >>>>>>>> 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> 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.
>> >>>>>>>>>>>
>> >>>>>>>>>>> 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 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 and here.
>> >>>>>>>>>>>
>> >>>>>>>>>>> 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
>> >>>>>>>>>>
>> >>>>>>>>>>
>> >>>>>>>>>> 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
>> >>>>>>>>>>>
>> >>> <image.gif>
>> >>>>>>>>>>>
>> >>>>>>>>>>> _______________________________________________________
>> >>>>>>>>>>> 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
>> >>>
>> >>> <image.gif>
>> >>>>>>>>
>> >>>>>>>>
>> >>>>>>>
>> >>>>>>> Thanks and Regards,
>> >>>>>>> Yash Jipkate
>> >>>>>>> Sophomore Undergraduate,
>> >>>>>>> IIT(BHU) Varanasi
>> >>>>>>> India
>> >>>
>> >>> <image.gif>
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>>>>>
>> >>> <image.gif>
>> >>>>>>
>> >>>>>>
>> >>>>>
>> >>> <image.gif>
>> >>>>
>> >>>>
>> >>>
>> >>> <image.gif>
>> >>>
>> >>>
>> >>>
>> >>> --
>> >>> Thanks and Regards,
>> >>> Yash Jipkate
>> >>> Sophomore Undergraduate,
>> >>> IIT(BHU) Varanasi
>> >>> India
>> >>>
>> >>> <image.gif>
>> >>>
>> >>>
>> >> <image.gif>
>> >>>
>> >>>
>> >>
>> >>
>> >> --
>> >> 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
>>
>
>
> --
> 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/20200311/3f452faa/attachment.htm>


More information about the fluid-work mailing list