Migrating content from the MkDocs version of farmOS.org

[jgaehring]

A lot of content from farmOS.org's "Development" tab has been moved over to the farmOS repository itself, but there is still quite a bit of content in the farmOS.org MkDocs repo that will still need to be migrated (or merged), as outlined in #22 (comment).

[jgaehring]

Note dump from my convo with @mstenta this morning...

Sitemap

This is the sitemap for the current (1.x) site, with notes on what to do with content of each page and its subsections:

• Home
  • logo --KEEP
  • screenshot --UPDATE
  • intro text --COPY
  • quick links --OMIT
    • these will be covered in the community/development/etc sections and menu
• Guide --OMIT
• Hosting --OMIT
• Develop --OMIT
• Community
  • Contribute --OMIT
  • Monthly Call
    • intro --COPY
    • call link
      • community/monthly-call/join -> meet.jit.si/farmos-community
    • remove "Use this calendar file" or create new one
    • Schedule --UPDATE
  • Chat (keep menu link)
  • Forum (keep menu link)
  • Farms: deprecate it (rename "early adopters" or "honor roll"?)
  • Maintainers
    • get bios
  • Supporters --COPY
  • Press --COPY
  • Trademark --COPY
• FAQ --OMIT
  • this would be great to move to Discourse, but not now
• Donate --COPY

Docs

We'll adopt this path structure:

/hosting (farmOS)

  /hosting/aggregator (farmOS-aggregator)

/development (farmOS)

  /development/js (farmOS.js)


  /development/py (farmOS.py)

/model

/donate

/community

  /community/monthly-call

  /community/...

I think this can all be done via the source-repos.js and _redirect files in this repo and the mkdocs.yml files in the source repos.

More...

• add source repo links to development/index.md
• remove "of Mike Stenta" from trademark footer

Redirects & Google analytics

• donate
• docs.farmos.org/*/ -> farmos.org/*/
• https://farmos.org/community/monthly-call/join -> https://meet.jit.si/farmos-community
• ...will follow up with more on this

[jgaehring]

So @paul121, a couple things to pull out from the above notes...

• add source repo links to development/index.md

Currently, there is no https://docs.farmos.org/development page, but that might actually be a good place to add links to the repositories for the source code itself, as mentioned in #21 and #22. Then we could use the webLinks from gatsby-source-git that you added for links to editing the actual documentation pages, like this.

Also regarding the /development path, Mike and I thought it would be nice to nest the docs for farmOS.py and farmOS.js under /development, along with the current farmOS development docs. So a more complete directory tree would be:

/development
  /development/api (farmOS)
  /development/module (farmOS)
  /development/environment (farmOS)
  /development/js (farmOS.js)
  /development/py (farmOS.py)

What do you think? And are you ok with using /py instead of /python?

[paul121]

Mike and I thought it would be nice to nest the docs for farmOS.py and farmOS.js under /development

I like that idea +1 !

Currently, there is no https://docs.farmos.org/development page, but that might actually be a good place to add links to the repositories for the source code itself,

How would this look in the menu? /development/introduction? I think that would be a nice addition regardless, but would also be good to link to the client libraries from within their own pages. If a user uses the menu to go directly to "farmOS.js Docs" you should be able to get to the source repo without going back to /development/introduction.

What do you think? And are you ok with using /py instead of /python?

A little weird 😄 haha Python just doesn't have the ubiquitous abbreviation that Javascript does. But in the sense that this is a reference to the farmOS.* client suffix it makes more sense.

Maybe better would be to just use the client library names themselves? Not so important for python, but would help to not confuse farmOS.js with Drupal javascript development? Also thinking if we have farmOS-map and farmOS-client docs in here later on - may be best to explicitly reference the library names?

[jgaehring]

I think that would be a nice addition regardless, but would also be good to link to the client libraries from within their own pages. If a user uses the menu to go directly to "farmOS.js Docs" you should be able to get to the source repo without going back to /development/introduction.

I guess this goes together with some ideas I've been stewing on WRT #22 as well (sorry I haven't responded there, might take me a little while today). I'm thinking it might be better to add it straight to the navigation menu on the left, with the "open-in-new" icon. I feel like it fits in better there than among the table of contents, since it links to another page, rather than a section of the page. And I feel like that gives it more prominence, as well.

Maybe better would be to just use the client library names themselves? Not so important for python, but would help to not confuse farmOS.js with Drupal javascript development? Also thinking if we have farmOS-map and farmOS-client docs in here later on - may be best to explicitly reference the library names?

Hmm, yea, these are all excellent points. We should all look at this together at some point.

I'm going to try a first pass at migrating stuff and seeing how it all fits together before we make any real decisions. I think it will be helpful to have that starting point, though, with nothing set in stone.

[jgaehring]

Maybe better would be to just use the client library names themselves? Not so important for python, but would help to not confuse farmOS.js with Drupal javascript development? Also thinking if we have farmOS-map and farmOS-client docs in here later on - may be best to explicitly reference the library names?

Thinking about this more today, and it makes more sense to me to use the project name for each of these. At least for JavaScript, there will be at least 3 separate projects written in JS, plus Drupal JS modules, all potentially leading to confusion. I suppose we could nest all of them under /js, but that seems unnecessary.

So how about this as a first draft of the sitemap, as what a combined mkdocs.yml might look like:

- Home: index.md
- Community:
  - Monthly Call: community/monthly-call.md
  - Chat: https://riot.im/app/#/room/#farmOS:matrix.org
  - Forum: https://farmOS.discourse.group/
  - Farms: community/farms.md
  - Maintainers: community/maintainers.md
  - Supporters: community/supporters.md
  - Press: community/press.md
  - Trademark: community/trademark.md
  - Donate: community/donate.md
- Data model:
  - Introduction: model/index.md
  - Record types:
    - Assets: model/type/asset.md
    - Logs: model/type/log.md
    - Quantities: model/type/quantity.md
    - Data streams: model/type/data_stream.md
    - Files: model/type/file.md
    - Terms: model/type/term.md
    - Plans: model/type/plan.md
    - Users: model/type/user.md
  - Logic:
    - Location: model/logic/location.md
    - Group membership: model/logic/group.md
    - Inventory: model/logic/inventory.md
  - Conventions: model/convention/index.md
- Development:
  - API:
    - Introduction: development/api/index.md
    - Authentication: development/api/authentication.md
    - Changes: development/api/changes.md
  - Module:
    - Getting started: development/module/index.md
    - Quick forms: development/module/quick.md
    - Entities: development/module/entities.md
    - Fields: development/module/fields.md
    - OAuth: development/module/oauth.md
    - Roles: development/module/roles.md
    - Services: development/module/services.md
    - Data streams: development/module/data_stream.md
    - Updates: development/module/updates.md
  - Environment:
    - Getting started: development/environment/index.md
    - HTTPS: development/environment/https.md
    - Updating: development/environment/update.md
    - Docker: development/environment/docker.md
    - PostgreSQL: development/environment/postgresql.md
    - Drush: development/environment/drush.md
    - Composer: development/environment/composer.md
    - Debugging: development/environment/debug.md
    - Automated tests: development/environment/tests.md
    - Coding standards: development/environment/code.md
    - Documentation: development/environment/documentation.md
  - farmOS.js:
    - Getting started: development/farmos-js/index.md
    - Schemata: development/farmos-js/schemata.md
    - Remotes: development/farmos-js/remotes.md
    - Entities: development/farmos-js/entities.md
    - Metadata: development/farmos-js/metadata.md
    - API reference: development/farmos-js/api.md
  - farmOS.py:
    - Getting started: development/farmos-py/index.md
    - Authorization: development/farmos-py/authorization.md
    - Resources: development/farmos-py/client_2x.md
    - Subrequests: development/farmos-py/subrequests.md
- Hosting:
  - Introduction: hosting/index.md
  - Installing: hosting/install.md
  - Updating: hosting/update.md
  - Email: hosting/email.md
  - 1.x Migration: hosting/migration.md

I may just go ahead with this if/when I get the chance, but please let me know what you think, @paul121 and @mstenta.

[paul121]

LGTM @jgaehring !

[mstenta]

Yea that looks great! +1

[jgaehring]

Alright! That took much longer than I hoped, but with 6c22954 and 19c2e89 I think I finally got the navigation how I described in #12 (comment) above. Here's the preview:

https://61bc99b94b6e470009434e56--gracious-brattain-bdd606.netlify.app/

I think it would be nice to shorten "farmOS.js Docs" and "farmOS.py Docs" to just "farmOS.js" and "farmOS.py", but that should be done from their respective source repositories. Apart from that, I've got a bit of tweaking to do, primarily with links and the monthly call schedule, but that really shouldn't take long.

In the meantime, @mstenta and @paul121, let me know if there's anything else to improve. Once this issue is closed, there won't be any other blockers, as far as I can tell, before making this the new farmos.org!

[jgaehring]

Oh, one remaining issue would be including a link to the v1 docs, but I don't think we've fully decided how to go about that yet, @mstenta. If you just want to keep building that w/ GH pages and hosting it on a subdomain, we can just add that link under "Development".

[mstenta]

one remaining issue would be including a link to the v1 docs

Oh yes, I think we should have a little bit of text on the homepage that emphasizes the 1.x vs 2.x difference and links to the 1.x docs. This would be temporary, in my opinion, but is important for clarity.

And related, we should also do this: https://github.com/farmOS/farmOS.org/issues/115

[jgaehring]

Oh yes, I think we should have a little bit of text on the homepage that emphasizes the 1.x vs 2.x difference and links to the 1.x docs. This would be temporary, in my opinion, but is important for clarity.

Feel free to open a PR if you know what that should sound like, or I can add something a little later.

[mstenta]

I'll add it to the new #23 and we can divide and conquer. :-)

[jgaehring]

Alright, as of 6063b29 I believe we're finished with most of the items in #12 (comment). What issues remain have been added to #23, where we'll wrap up tracking changes prior to launch.