Add another source repo

[jgaehring]

I don't know if this should be a "must-have" prior to deployment, since it's not strictly necessary, but would cement this as a proof-of-concept to demonstrate how the architecture works with multiple source repos.

As I mentioned on the forum and in #7:

This opened up a whole can of worms regarding how the navigation is structured, such as how the navigation of a particular project’s documentation relates to the overall navigation for the site in general. Right now, it’s hard to to really anticipate what this should look like, since it won’t really be an issue until we’re using more than one source repository.

So I guess this depends on two other related issues, both of which are quite substantial.

First is how to structure the navigation data (eg, nav in mkdocs.yml) and how that gets handled as a GraphQL node in Gatsby. This can be done right now, but I think there are some major changes I could make so this is easier to do for each source repo we want to add. As I also mentioned in #7:

There are a lot of hairy details in this, but I'll definitely need to add a gatsby-browser.js file, and I probably want to consolidate some of the configuration for the source repos in gatsby-config.js, and streamline how that config is queried in gatsby-node.js. I may be able to resolve this w/o totally overhauling everything, so I might revisit it sooner than later, just not going to let myself get bogged down or blocked by this before putting this into production.

Second is the impact on the UI itself. Right now, the page layout is still structured for a single source of documentation, so we'll have to rethink how to allow navigation between different docs, what to use as a homepage, etc, etc. Part and parcel of that is issue #1. There's also the aspect of the sitemap itself, as I mentioned way back in May on the forum:

Basically, I'm thinking about the ultimate configuration, when this becomes farmos.org, how do we breakdown the paths to the different projects' documentation?

• One option...
  • farmos.org/docs/farmos/
  • farmos.org/docs/field-kit/
  • farmos.org/user-guide/farmos/
• Another option...
  • farmos.org/farmos/docs/
  • farmos.org/farmos/user-guide/
  • farmos.org/field-kit/docs/
  • farmos.org/field-kit/user-guide/
• And yet another...
  • farmos.org/docs/ (main farmOS docs)
  • farmos.org/user-guide/ (main farmOS user guide)
  • farmos.org/field-kit/docs/
  • farmos.org/field-kit/user-guide/
• etc.

I could go on ad nauseam. Lots of options, probably necessitating a larger discussion, and some passage of time to see how the rest of the redesign shakes out.

So yea, many more issues fall out from this one as soon as you start tugging at the threads. But none of them are intractable, imo. I think most of them boil down to lots of decisions that need to be made, but the implementation should be pretty straightforward after that. It will simply take some conversation(s) to get to that point.

[jgaehring]

Oh, and regarding which repo(s) to use as an additional source, I think the Field Kit repo (farmOS-client) would be good to use once those docs are updated properly. I'm happy to try out farmOS-aggregator or farmOS.py, too, if @paul121 wants to add the action workflows to those repos, once I get them finalized. They would just need something to provide the navigation data, either a YAML file like mkdocs.yml, or Frontmatter in the markdown files.

[jgaehring]

First is how to structure the navigation data (eg, nav in mkdocs.yml) and how that gets handled as a GraphQL node in Gatsby.

This has been resolved. See #7 (comment). Main blocker now is the UI itself and corresponding decisions about routes etc.

[jgaehring]

I think the Field Kit repo (farmOS-client) would be good to use once those docs are updated properly.

As I mentioned in farmOS/farmOS.js#50, it'd be even better to start sourcing that library's docs as soon as the beta is released, which should be well ahead of FK's beta.

[jgaehring]

Over the weekend I added farmOS.js to the list of source repos (bbd1eac), and also added some configuration and the GHA workflow to the farmOS.js repo (farmOS/farmOS.js@7e9fc82 and farmOS/farmOS.js@4162e60 respectively). As expected, there are several issues that still need to be resolved. The main ones that jump out:

• No way to navigate from the farmOS docs to the farmOS.js docs
• No navigation options for farmOS.js in the nav drawer even when you're viewing farmOS.js docs, largely due to this.
• Only the first h1 header is being displayed in the ToC
• Error caused by the IntersectionObserver when navigating to another URL via the address bar, although that may only be in the dev env.
• Netlify builds are breaking when triggered by farmOS.js and farmOS repos (see the Dec 3 build).

And I'm sure there are more if I took the time to investigate, but I don't really have time to do so now. Hopefully I'll get a chance to resolve some of these issues this upcoming weekend, or at least document them a little better, but if not, this may have to wait til the holiday break.

[jgaehring]

Ok, I managed to knock out a few more of the issues cited in the last comment. The first two navigation issues were resolved by bfae288 and the IntersectoinObserver issue by dde4781.

So far I haven't seen any more issues with the Netlify builds, so scratch that for now, but it's something to keep our eyes on.

That just leaves the ToC issue, and I'm going to open a separate issue for that.

There are plenty more issues that will fall out of this, but I'm going to close this since the bigger issue now is how to manage multiple sources of content for the site in general, not just how this one additional source effects things.