migrate the docs

[stan-dot]

• squash the commits that change the contents - (all except the first one)

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 91.06%. Comparing base (a476f08) to head (f3ff32e).

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #448   +/-   ##
=======================================
  Coverage   91.06%   91.06%           
=======================================
  Files          40       40           
  Lines        1667     1667           
=======================================
  Hits         1518     1518           
  Misses        149      149           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[stan-dot]

/home/runner/work/blueapi/blueapi/docs/reference.md:5: WARNING: toctree contains reference to document 'reference/cli' that doesn't have a title: no link will be generated
one small error with toctree extension - might be rst specific, need equivalent for md

[callumforrester]

Git appears to see these as deleting old files and creating new ones, rather than renaming. Can we somehow preserve history?

[stan-dot]

we cannot preserve that, renaming the file extension makes the change.

[DiamondJoseph]

we cannot preserve that, renaming the file extension makes the change.

Can you try renaming the files, committing, then replacing the contents, committing again?

[joeshannon]

we cannot preserve that, renaming the file extension makes the change.

Identifying renames in git is essentially a guess based on the similarity of the files before and after the rename, the actual names don't matter. According to the git docs the default similarity index is 50%, presumably GitHub uses that too.

Joseph's suggestion is what I would normally recommend as it makes it slightly easier to see what happened in the history and since the rename is separated from the content change git log --follow <file> would work, although as we are squash merging it would result in the same state when merged into main (unless it was split into two PRs or equivalent).

[stan-dot]

why do we care about the exact history? this app has only been run on 1 live beamline.

I'll check the history thing on Tuesday if time allows

[callumforrester]

This needs to be two commits:

1. Changes the file names
2. Changes the file contents
   It then needs to be merged without squashing

[stan-dot]

that here is quite odd

[stan-dot]

todo: need to remove the sphinx dependency and the CI jobs: ERROR: InvocationError for command /opt/hostedtoolcache/Python/3.11.9/x64/bin/sphinx-build -EW --keep-going -T docs build/html (exited with code 1)

moving the docs build config to reflect the one in the copier template

[DiamondJoseph]

Don't these files require changes?

[stan-dot]

ok will review those all

[stan-dot]

no idea what is this about, :show-nested:, it couldn't be less informative

[stan-dot]

what is this???

[DiamondJoseph]

what is this???

It appears to be embedding the rst inside the md rather than doing the equivalent md formatting :D

[stan-dot]

what is this???

It appears to be embedding the rst inside the md rather than doing the equivalent md formatting :D

I know that , it's an artifact from a fully rst times. But what sorcery did it do behind the scenes to dynamically import version like that? Do we want to support this in md?

[DiamondJoseph]

It's part of the configured tooling.
https://github.com/DiamondLightSource/blueapi/blob/main/pyproject.toml#L72

I think it is correct for it to be there (it is available to call blueapi version after pip installing)

[stan-dot]

I am not sure that markdown supports dynamic imports into markdown like this

[stan-dot]

I don't think that markdown calls this rightly, this is redundant information that could be deleted from api.md

@DiamondJoseph

[stan-dot]

closed by misclick

[stan-dot]

following this comment to get it to work

[callumforrester]

LGTM, thanks!