Where:
https://docs.foundries.io/latest/reference-manual/linux/linux-update.html?#updating-the-linux-microplatform-core

What:
If the subscriber wants to "undo" a merge of LmP we recommend:
git reset --hard HEAD~1

However, that means we will need to "force" the next command:
git push -f

The default git version in macOS Mojave is 2.21
The update-factory-manifest script uses:
git branch --show-current
which is not supported necessitating updating git to the latest version.

Note - not tested on macOS Catalina

Since we have fioctl in the make-docs step of our CI now, it would be easy to start showing the output of commands automatically by using sphinxcontrib.programoutput.

In the docs, we would put something like

.. program-output:: fioctl version

which would return (at time of writing) the following, inside of a code block.

78011c6

This has the additional benefit of failing the doc build process if a command fails with an exit code greater than 0. This would mean we would be alerted by the doc failing when some of the Fioctl commands have been entirely deprecated and removed. It would also allow @doanac to add a special exit code to a deprecated command that would produce the same result even if it has not failed from the perspective of the user, i.e a deprecation warning.

Here:
https://docs.foundries.io/latest/reference-manual/linux/linux-targets.html?highlight=gateway

We refer to lmp-gateway-image-* files for flashing.
This is being changed to lmp-base-console-image-* with the release of v75.

Things we can't do without great difficulty in Sphinx:

• Insert device related info on a page (with conditionals) #164 (comment)

• E.g: If this page has the "imx8mm" tag, then insert a link in a note at the bottom
  of page

• Collaborate easily as a team (All written in markdown)

  • Well thought out and separated functionality for
    • Writers (Us)
    • Designers (Milo)
    • Contributors (Anyone)
      This is demonstrated here

Who uses it?

• GlusterFS
• Traefik
• Flox

Benefits

• Most of the Sphinx plugins we are using are native functionality in MkDocs.

• No cruft. Sphinx was developed to document Python code, thus has a lot of
  superfluous functionality that often gets in the way of the way we want to
  document normal things. This is primarily why RST is used.

  • Cares about indendation (Makes development slower and expression of spaces and newlines harder due to the amount of technicalities with indentation)
  • Too strict (Makes CI really hard due to false positive errors that cannot easily be ignored or turned off)

• Better SEO (via tags and author details, etc.) #137

Notes

• Small but determined community, available in the #mkdocs IRC

  • Usually pretty responsive
  • Issues are fixed in days

• Written in Python, just like Sphinx.

• Provides Jinja templating with conditionals as native functionality

  • #164 (comment)

• Is just plain better than Sphinx for what we're doing

Yocto developers

Wrote their own incomplete pre-processor just to replace ampersand &variable's

These variables are global, meaning we still cannot make smart pages and
templates that fill out depending on local variables like the architecture the
file says it represents - using markdown tags/labels for example: (%arm64,
%riscv64, %etc).

• Nicolas Dechesne had to write these pre-processors in Python
  Commit1
  Commit2

Currently, 'targets.json' does not link to the terminology section each time it is mentioned, it should.

I could not find any LICENSE file in this repository.

Under which license is this repository licensed?

Reference: https://choosealicense.com/

This stops the builders from generating a new build for this push

In the example:

View log of config changes (similar to "git log")

fioctl config log
I get the error:
Error required flag "factory" not set

To get around this I needed to add the --factory flag
fioctl --factory config log

https://docs.foundries.io/latest/reference/linux-targets.html?highlight=machines

At time of writing, this section refers to the setup-environment script. This specific workflow is now with editing the machine: key value in factory-config.yml. This needs to be updated to reflect this.

xref = cross-reference

This issue should be closed when all non xreffed duplication is gone from the docs. When I remove duplicates I'll reference this issue in the commit.

As an example, there are 3 mentions of netrc in the documentation which could be culled and replaced with one xref that displays like this if we install the sphinx-hoverxref role for the docs.

Example from Sphinx official docs

In this example, the word Markdown is written in the .rst file as referencing another .rst file in the doctree. So it renders the actual page for the referenced document and displays it in a nice popup. This should be done for all things that are significant that currently seem to have duplicate mentions. Duplicate mentions implies significance, so those things, whatever they may be should get their own doc file and be referenced like this to avoid fragmentation.

:ref:`Markdown <intro/getting-started-with-sphinx:Using Markdown with Sphinx>`

The source for this example can be found here

Regarding:
https://docs.foundries.io/latest/reference-manual/security/device-gateway.html#setting-up-your-pki

There is some confusion that the fioctl keys ca create /absolute/path/to/certs/ command creates EVERYTHING you need to start provisioning device-based certificates. Not exactly sure how that can be made more clear.

The Terminology section is great, but it has the side-effect of "burying" the fioctl command that you need to run first.

The documentation states that user should generate a token after factory is created, but what actually happened is that I received an email that contained a one-time download link to get the token needed to access the factory.

https://docs.foundries.io/latest/customer-factory/getting-started.html#generate-an-access-token

In the reference manual we have fioctl in the OTA section. I think this belongs in the top "Foundries Factory" section.

Upon Factory creation you will be sent an email containing your Offline FoundriesFactory TUF Keys. Read this documentation for information on key rotation.

That's good stuff. Given that its just a "note". I think the more important task to stress is storing this file securely. So maybe it should be something like:
Upon Factory creation you will be sent an email containing your Offline FoundriesFactory TUF Keys. Please keep this file stored securely.

The Linux microPlatform supports a wide range of platforms out of the box. We even provide QEMU images for ARM and RISC-V architectures.

I'm terrible with writing but I think we've generally avoided using 1st person voices. So maybe this could be:
The Linux microPlatform supports a wide range of platforms out of the box even including QEMU images for ARM and RISC-V architectures.

I think "git" needs to be "Git" based on the limited googling I've done: https://ci.foundries.io/projects/fio-docs/builds/558/docs/artifacts/html/getting-started/git-config/index.html

https://docs.foundries.io/latest/reference-manual/linux/linux-building.html covers the build from source process using the public repos (public lmp) only.

We should extend that page covering how to build lmp from source based on a certain factory/branch, and explain the difference between a factory build and our public build.

I have been asked especially to include the se050 docs at the URL https://app.foundries.io/docs/latest/reference/secure-element.050.html

These docs have not yet been pulled into refactor, so this issue is noting that they should be included.

I want to put simple variables/substitutions into the docs. This has proven hard, because Sphinx does not have a pre-processor with which to replace text, it uses RST and inherits basic substitution as a result

Assuming the substitution |ARCH| is defined as x86_64 by having .. |ARCH| replace:: x86_64 set in an included file:

├── reference-manual
│   ├── qemu
│   │   ├── arm64.rst
│   │   ├── arm64-substitutions.yaml <---- 
│   │   ├── generic-prepare.template
│   │   ├── qemu.rst
│   │   ├── riscv64.rst
│   │   ├── riscv64-substitutions.yaml <---- 
│   │   ├── x86_64.rst
│   │   └── x86_64-substitutions.yaml <---- 

We cannot do the following:

Conditionally/Variably include documents based ARCH.

.. include:: |ARCH|-qemu-command.rst

.. asciinema:: ./demo/|ARCH|.cast

We can do things like this, though:

.. |ARCH| replace:: x86_64
.. |MACHINE| replace:: intel-corei7-64
.. |FIRMWARE_BLOB| replace:: ovmf.qcow2

.. parsed-literal::

     └── |ARCH|
         ├── lmp-factory-image-|MACHINE|.wic.gz
         └── |FIRMWARE_BLOB|

Resolves to:

     └── x86_64
         ├── lmp-factory-image-intel-corei7-64.wic.gz
         └── ovmf.qcow2

@MatthewCroughan - this is probably something we should raise as another bug, but ... The current docs explain how to do what we call a "root key rotation". We'll need to eventually explain a procedure for updating a factory's "targets" signing key as well.

Originally posted by @doanac in #67 (comment)

Currently lacking a definition.

When setting up for a local build using the instructions here: https://docs.foundries.io/latest/reference/linux-building.html#set-up-work-environment

The example states:
MACHINE=raspberrypi3-64 source setup-environment [BUILDDIR]

but BUILDDIR (if used) must be in the lmp directory or your build will fail

Reproduce:

MACHINE=raspberrypi3-64 source setup-environment ~/raspberrypi3-64

dgriego@foundries-x86-build:~/lmp/home/dgriego/raspberrypi3-64$ bitbake -s
ERROR: Unable to start bitbake server (None)
ERROR: Server log for this session (/home/dgriego/lmp/home/dgriego/raspberrypi3-64/bitbake-cookerdaemon.log):
--- Starting bitbake server pid 17433 at 2020-07-08 16:18:20.983557 ---
ERROR: The following layer directories do not exist:
ERROR: /home/dgriego/lmp/home/dgriego/raspberrypi3-64/conf/../../layers/meta-lmp/meta-lmp-base
ERROR: /home/dgriego/lmp/home/dgriego/raspberrypi3-64/conf/../../layers/meta-openembedded/meta-oe
ERROR: /home/dgriego/lmp/home/dgriego/raspberrypi3-64/conf/../../layers/meta-openembedded/meta-networking
{snip}

For some reason, literal blocks are syntax highlighted which is annoying when trying to show something like terminal output, or a single line command.

The following should not highlight, but it does.

Thing::
  Test 123567

• This issue should be closed when the refactor branch is considered complete.

• Commits that fix issues relating to the title should be referenced to this issue.

https://docs.foundries.io/71/reference/container-secrets.html#quick-background-on-ci-secrets

There is a bit of documentation here that refers to a directory called /secrets/. If someone understands both what a CI system is and the concept of secrets, they may infer that this directory is on the machine running the CI software (jobserv in this case.) However, upon first read, one can incorrectly assume this is referring to a directory on their local development machine, or the machine running LMP.

This is just one example of not being explicit enough where operations are happening, or how they occur, since an understanding of CI/Secrets is presumed in this case. This issue is just to make a note that this is something that occurs currently in the docs, and I will reference this issue with commits when issues like it are fixed.

I also hear it's possible to modify this via fioconfig and that images configured with the aktualizr-no-prune label will not prune.

https://github.com/foundriesio/aktualizr-lite/blob/91c2e6a75adc7671823c2059a62f93f91465b8dd/src/composeappmanager.cc#L164

We've been asked to look into some SEO enhancements after a few crawls of our websites have been performed and SEO-related issues have been detected.

I tried to look into solving some of those, but I have no idea how to achieve that with Sphinx (or if it's even possible).

The issues we should try to fix are:

• Missing canonical link in each page
  Pages like this can also be accessed and indexed without the trailing index.html (here) and should contain a canonical link (ideally to the one without the index.html) or search engines will consider the content as duplicate, and index it twice. I looked into Sphinx docs, but could not find an easy solution without having to hack the Sphinx theme.
• Missing publisher, author, datePublished (and possibly others) tags in each page
  I'm not even sure if we can or want to fix those. These are parts of what Google call structured data and results in higher page rankings, better search results etc.... I know what needs to be added to the pages, I have no idea how to achieve that with Sphinx.

Upon noting #93, I noticed that app.foundries.io/docs resolves and does not redirect to docs.foundries.io. @MiloCasagrande has noted that we should redirect to docs.foundries.io in the future. I am noting down this issue as not to forget and to fill out more details that are important, since this may be a reference for future issues that may occur due to the change. (hopefully not)

aktualizr-lite just added a new flag for controlling a feature:

https://github.com/foundriesio/aktualizr-lite/pull/27/files

We should add this to https://github.com/foundriesio/docs/blob/master/source/reference/aktualizr-lite.rst. Probably need a section for interesting config options.

It should be considered how to best integrate the automated documentation from foundriesio/fioctl#55. I like the idea of having a man-pages section/folder, much like OpenZFS has recently started to do with their sphinx docs and just placing it all in there.

https://openzfs.github.io/openzfs-docs/man/index.html

Since I am currently working on #88, it would be best to merge this first, then make a separate PR which integrates this CI and solves this issue, so we can take the content that I have produced and put in its correct location.

Based on https://github.com/Freescale/meta-freescale/blob/master/classes/fsl-eula-unpack.bbclass#L126

This is done automatically on our CI, but is also required for people building locally form the upstream/factory lmp-manifest.

https://docs.foundries.io/71/customer-factory/getting-started.html?highlight=netrc

The .netrc file is not something familiar to everyone. Upon first reading of the docs I was confused about its significance. Currently it comes across as a magical file that is related to fioctl by the order the doc places reference to this file in. Certainly I am too young to know what it is.

It goes unmentioned that .netrc also configures credentials for git, this should be mentioned in some manner. The purpose of creating .netrc is to configure both fioctl and git. We should have an xref that links to the generic documentation for netrc as well as our own documentation for how to use it and why we are using it.

Since we have the expertise we can even go as far as to link the source code for git itself that is responsible for checking this file.

These guys also happen to have a good reference for documenting this file and how it should be used on all operating systems including Linux, macOS and Win7

My following of this doc lead to me recreating this issue readthedocs/readthedocs.org#2116.

This means my removal of app.add_stylesheet() in favor of html_context = here #73 was premature and requires fixing. Because of this, usage of sphinx-tabs and contentui is broken so I need to fix it, but this is lower priority than writing docs so I am just using a local change for now before I submit a PR with the fix.

Noting so that I do not forget to add it. I'm going to be referencing QEMU every now and then, and I want it to be possible to link to the same QEMU link by just stating:

:xref:`qemu`

https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html

This would allow us to embed terminal output into the docs in an animated format which could be useful for all sorts of demonstrations without taking up the whole page with the output. Longer term addition.

• lmp-auto-hostname is added to the end of CORE_IMAGE_BASE_INSTALL first, but diff has it at the beginning
• We should say LMP_HOSTNAME_MODE is set to serial by default (so if unset, serial will be used)
• lmp-device-auto-register is also added to the end first, and diff showing at the beginning
• We should have a step doing 'mkdir -p recipes-support/lmp-device-auto-register/lmp-device-auto-register' for having the directory there
• We are using meta-subscriber-overrides as the base folder for most instructions but the one for api-token (it starts with recipes-support instead)