Regarding project "Refactor and Automate Infusion Documentation"

Yash Jipkate yashjipkate at gmail.com
Thu Mar 19 17:52:30 UTC 2020


Hi,

I have uploaded the draft proposal on the GSoC dashboard. I am looking
forward to your feedback!

Thanks.
Yash



On Wed, Mar 18, 2020 at 4:53 PM Justin Obara <obara.justin at gmail.com> wrote:

> Hi Yash,
>
> You’d need to follow the Deploy
> <https://github.com/fluid-project/infusion-docs#deploy> instructions
> listed in the README. The changes in the deploy branch are then picked up
> by our Jenkins CI and deployed to our own servers. You should probably
> leave room in your proposal for adjusting the deploy/CI/hosting methods.
>
> Thanks
> Justin
>
> On Mar 18, 2020, at 3:59 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>
> Hi Justin,
>
> I wanted to know how is the current site hosted. I am currently writing my
> proposal and I need to know the current method of deployment so I can
> search about how to deploy HUGO on it and write about it in my proposal.
>
> Thanks
> Yash
>
> On Mon, Mar 16, 2020 at 9:00 PM Justin Obara <obara.justin at gmail.com>
> wrote:
>
>> I guess it’s something we can discuss and you can add to your proposal.
>> It’s something I would have to think about more, but we could look into
>> solving this through convention, or look into if there is a common front
>> matter that makes sense to include.
>>
>> Thanks
>> Justin
>>
>> On Mar 16, 2020, at 11:21 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>>
>> Hi Justin,
>>
>> I noticed that in the current setup we use front matter to specify the
>> title of the page. But since we need to migrate all SSG related data, this
>> would mean that front-matter should not be present in the content files.
>> But not all titles can be automated in pre-configured front-matter. For
>> example, MInimalFootprint.md
>> <https://github.com/fluid-project/infusion-docs/blob/master/src/documents/tutorial-prefsFrameworkMinimalFootprint/MinimalFootprint.md> has
>> the title 'Preferences Framework: Minimal Footprint' which can not be
>> referred from its filename as was my plan for possible automation. Should
>> we allow the title in the front matter in the content repo? I personally
>> suggest that we should keep it since irrespective of the framework used,
>> the title is something that is common to all SSGs' front-matter.
>>
>> What do you think about it?
>>
>> Thanks
>> Yash
>>
>>
>> On Thu, Mar 12, 2020 at 7:22 PM Justin Obara <obara.justin at gmail.com>
>> wrote:
>>
>>> Hi Yash,
>>>
>>> Sounds good.
>>>
>>> Thanks
>>>
>>> On Mar 12, 2020, at 9:27 AM, Yash Jipkate <yashjipkate at gmail.com> wrote:
>>>
>>> Hi Justin,
>>>
>>> I too think that we might have gone too deep into implementation
>>> details. I will try to keep my discussion to immediate doubts and parts of
>>> the codebase that I am facing difficulties with. Thanks for pointing out.
>>>
>>> Thanks.
>>> Yash
>>>
>>>
>>> On Thu, Mar 12, 2020 at 5:39 PM Justin Obara <obara.justin at gmail.com>
>>> wrote:
>>>
>>>> Hi Yash,
>>>>
>>>> Please see replies below
>>>>
>>>> Thanks
>>>> Justin
>>>>
>>>> On Mar 12, 2020, at 2:06 AM, Yash Jipkate <yashjipkate at gmail.com>
>>>> wrote:
>>>>
>>>> Hi Justin,
>>>>
>>>> I have replied inline, I also had some questions regarding the project.
>>>>
>>>>    - What is the current method of deployment of the docs? There are
>>>>    lines like this
>>>>    <https://github.com/fluid-project/infusion-docs/blob/05bba0b6e2509241b13d4b5c50656914b1e30314/src/layouts/default.html.handlebars#L64> in
>>>>    the infusion-docs repo that uses relativeUrl to access something not
>>>>    included in the repo. From what I understand from the urijs docs,
>>>>    relativeUrl gets the relative URL of the argument w.r.t the current URL.
>>>>    But there is no such folder in the repo. In the link that I mentioned, the
>>>>    path is of the main infusion repo which is hosted somewhere else. How is
>>>>    the relative URL working if they are hosted differently?
>>>>
>>>> It looks like they are being copied to the correct location by the
>>>> copyDeps
>>>> <https://github.com/fluid-project/infusion-docs/blob/master/docpad.js#L69-L112> function
>>>> in docpad.js. They are originally pulled in as dependencies listed in the
>>>> package.json
>>>> <https://github.com/fluid-project/infusion-docs/blob/master/package.json#L15-L32>
>>>>  file.
>>>>
>>>
>>> It seems that it is a way of managing external dependencies. I found this
>>> blog
>>> <https://janaksingh.com/blog/hugo-package-management-folder-mounts/> that
>>> describes how to do this in HUGO.
>>>
>>>>
>>>>    - Since the migration is not incremental, how should this be
>>>>    carried out? I cannot modify the structure of the documents to
>>>>    HUGO-friendly and expect DocPad to keep running. One way to make this
>>>>    happen is to have a fork of the docs repo and then carry out the
>>>>    modifications there and merge it only when it is in a deployable state,
>>>>    i.e. when the HUGO repo is also ready. What do you think?
>>>>
>>>> Yes, you should be doing your work in a separate branch. It probably
>>>> makes sense to start off with some mock content, that is something small to
>>>> work with to get the pieces sorted out.
>>>>
>>>
>>> So, I would make a smaller version of the docs website with just a few
>>> docs and complete it with the corresponding HUGO code as well and then add
>>> the rest of the docs.
>>>
>>>>
>>>>    - Do we change the design of the site? There are many good themes
>>>>    available on HUGO which are ready to use. We can use them for the site and
>>>>    would give it a new look. If we don't change the design of the site then a
>>>>    custom theme needs to be built from scratch.
>>>>
>>>> I think for now expect that we’ll keep the same site design, but this
>>>> is something that can be discussed and researched as well.
>>>>
>>>>
>>>> Thanks.
>>>> Yash
>>>>
>>>>
>>>>
>>>>
>>>> On Wed, Mar 11, 2020 at 6:15 PM Justin Obara <obara.justin at gmail.com>
>>>> wrote:
>>>>
>>>>> Hi Yash,
>>>>>
>>>>> As usual comments below.
>>>>>
>>>>> Thanks
>>>>> Justin
>>>>>
>>>>> On Mar 10, 2020, at 3:05 PM, Yash Jipkate <yashjipkate at gmail.com>
>>>>> wrote:
>>>>>
>>>>>
>>>>> 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.
>>>>>
>>>>>
>>>>> Thanks for the detailed explanation. I actually meant that you would
>>>>> have to create something as part of your import script that read in the
>>>>> config doc and placed the files and directories in the locations that are
>>>>> needed for the SSG.
>>>>>
>>>>
>>>> Ah, yes. The script would be configured to import the contents of the
>>>> repo so that the imported documents are placed in their expected locations.
>>>>
>>>>>
>>>>>
>>>>>>
>>>>>> >
>>>>>>> > 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 relative paths to images should work on GitHub. You can see the “Creating
>>>>> a New Adjuster UI
>>>>> <https://github.com/fluid-project/infusion-docs/blob/master/src/documents/tutorial-prefsFramework/CreatingANewAdjusterUI.md>”
>>>>> markdown file from our repo as an example. The links between documents is a
>>>>> bit harder because png GitHub you have to reference “.md” files and on the
>>>>> site you’ll reference “.html” files. In our current site, you can see that
>>>>> we transform the URLs to be correct when generating the site.
>>>>>
>>>>> It’s preferable for the links in GitHub to be self referential so that
>>>>> if the website is down, or if you just clone the docs repo and use that
>>>>> locally, the links still work. Also, if you are creating new docs or
>>>>> modifying existing ones, you’ll be able to test that the URLs are working.
>>>>>
>>>>
>>>> This is an issue with HUGO that it doesn't render the images when
>>>> relative URLs are used. I have opened a ticket
>>>> <https://discourse.gohugo.io/t/how-to-render-image-in-github-markdown/23951/2> in
>>>> the support forum of HUGO. I also saw some previous
>>>> <https://discourse.gohugo.io/t/image-path/1721> tickets
>>>> <https://discourse.gohugo.io/t/is-there-a-way-to-control-markdown-images-in-hugo/6687/4>
>>>>  related to this topic. I got a reply from the team in which he gave
>>>> me a link to one of his projects
>>>> <https://github.com/bep/portable-hugo-links> where he achieved this.
>>>> In HUGO there is a feature where we can convert a page into a bundle (like
>>>> in the repo p1
>>>> <https://github.com/bep/portable-hugo-links/tree/master/blog/p1> is
>>>> converted to a bundle - by adding index.md) so the links would work both in
>>>> preview as well as the site.
>>>>
>>>> We will have to make all those pages which are having images into
>>>> bundles. This is done by having a directory with the name of the page and
>>>> an index.md and the images in that directory. The import script would take
>>>> the name of such MD files from the docs repo and make them into folder
>>>> names and then import the images required into that directory. One way to
>>>> conveniently carry this out would be to have these types of directories in
>>>> the contents repo itself. Say, there is currently a doc *blog.md *which
>>>> uses *img.png* stored in images/, we can re-organize this into a *blog* directory
>>>> with *index.md *and the *img.png* in it. This way it would be easier
>>>> to group the pages and their resources in one place and avoid unnecessary
>>>> scripting and heavy coupling which would be vulnerable to breakage.
>>>>
>>>>
>>>> I’m not sure if I’m not fully understanding the issue, but it doesn’t
>>>> seem to be a problem or require a complex solution. For example it seems
>>>> like images should work from an image directory under in the static
>>>> directory ( https://discourse.gohugo.io/t/image-path/1721/3 ). Another
>>>> way would be to use markdown render hooks
>>>> <https://gohugo.io/getting-started/configuration-markup/#markdown-render-hooks>.
>>>> Anyways, I wonder if we’re getting into too much specifics. It might be
>>>> better to think of the end goal, and then think of how to get there with a
>>>> few systems. Then you can compare the pros and cons. Perhaps this is what
>>>> you are doing here with Hugo. I’m just saying that we shouldn’t get too far
>>>> ahead with implementation details just yet.
>>>>
>>>
>>> Actually, in the post you referred, the way he mentioned would only
>>> display it in the rendered HTML. I have tried it for myself. The markdown
>>> render hook method can also be looked upon. This method makes use of page
>>> resources whereas the page bundle method renders the image just by
>>> referring the relative path. I will look at the pros and cons of both the
>>> methods and then decide on one.
>>>
>>>>
>>>>
>>>>>
>>>>>> >
>>>>>>> > 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
>>>>>>
>>>>>> <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: <http://lists.idrc.ocad.ca/pipermail/fluid-work/attachments/20200319/5344ccdc/attachment.html>


More information about the fluid-work mailing list