Make the home page easier to navigate

[prjemian]

• close Make home page easier to use. #326

[prjemian]

A built ZIP file of the docs are uploaded as an artifact: https://github.com/bluesky/hklpy/actions/runs/8890336016

Here's a screen view:

[prjemian]

Ready for review, no real changes to content, just presentation, aimed at making it easier to navigate.

@ambarb - Comments?

[padraic-shafer]

I like the gist of these changes.

The grid does a good job of calling attention, but I think it's overwhelming. Breaking it up into sections would help. My suggestion is to split them, such as:

1. Top row -- it's the primary focus for newcomers
2. Middle two rows -- Give them a header or introductory sentence such as "hklpy modules" or "Learn about hklpy"
3. "Miscellaneous" -- Last row with more esoteric info

The overview text could be a bit clearer. Suggestion...

`hklpy` is a python package that makes it practical to use the `hkl` library with `ophyd` devices and `bluesky` plans.

Multiple `libhkl` repositories exist; `hklpy` uses the version at XXX for underlying functionality.

[prjemian]

@padraic-shafer - Thanks for the feedback. I agree there is still too much information on the home page. Rather than adding sections, I'd like to keep the page at a very high level. I'll build your phrasing into the overview text, while keeping it oriented to the needs of the crystallographer who is not familiar with package names and libraries. The intent, eventually, is to expand from the Hkl library to other computational backends.

[prjemian]

home page (some cards have been moved to new User Guide page)

[padraic-shafer]

home page (some cards have been moved to new User Guide page)

I find that much easier to digest. Nicely done!

[prjemian]

@rodolakis has been guiding me to say the same thing (in documentation) with fewer words. Applying that here.

Newly-created User Guide gathers some of content pulled from home page, and groups as @padraic-shafer suggested:

Install page completely revamped. Most other pages left alone.

Summary

Overhaul of appearance, not substance.

[prjemian]

Reviewers, get ZIP file from https://github.com/bluesky/hklpy/actions/runs/8901753697

[ambarb]

@prjemian the new layout/design looks great. I spent more time exploring and finding the spec-to-bluesky was not something I had seen before. I imagine this is part of your objective.

unrelated to this review, I have two comment for consideration:

1. maybe it would be good to add in the d_object.move((h, k, l)) description that people should not use that within a RE script. they should use bps.mv()
2. does reflex work like fourc's reflex (in that the lattice parameters are refined )?

[prjemian]

@prjemian the new layout/design looks great. I spent more time exploring and finding the spec-to-bluesky was not something I had seen before. I imagine this is part of your objective.

💯

unrelated to this review, I have two comment for consideration:

1. maybe it would be good to add in the d_object.move((h, k, l)) description that people should not use that within a RE script. they should use bps.mv()

Good point. I'll add this.

2. does reflex work like fourc's reflex (in that the lattice parameters are refined )?

Have not seen lattice parameter refinement in the libhkl code. I'll look for it.

[prjemian]

@ambarb - Found it. SPEC's reflex is affine in libhkl. See https://blueskyproject.io/hklpy/sample.html#hkl.sample.HklSample.affine

The only advice I have now is to consult the libhkl documentation. Start with section 1.5.2:

It is also possible to calculate U without the knowledge of crystalline parameters. It is then necessary to refine the parameters. This is the same as minimizing a function. We will use the simplex method to find this minimum and therefore adjust the set of crystal parameters as well as the orientation matrix.

Also section 1.5.4. That part of the docs are in French.

[prjemian]

[prjemian]

To help with review, I pushed the new docs to the web site: https://blueskyproject.io/hklpy/

(It's easy for me to push the old version to the web site. We're not ready, yet, to support multiple versions of the docs on the web site. Probably that will come sometime this year.)

[maffettone]

This is great, I like the way it progressed and the landing page developed above. I followed all links, and nothing is dead or misdirecting.

Only 1 comment:
The release history confuses me. I think it makes sense to have place holders in the comments, so that changes don't get lost. But History probably shouldn't include the future.

[prjemian]

History probably shouldn't include the future

I tend to agree. I see value in documenting changes in the repo in public, for those who work out of the main branch. But for now, all future changes are noted as comments.

[prjemian]

I'm hearing consensus overall to these changes but no one has approved. I plan to merge tomorrow if there is nothing else to be changed.

[mrakitin]

After-merge review :)

[mrakitin]

That's a nice feature so that all HowTo's can be included automatically.

[mrakitin]

blueskyproject.io may be better to avoid redirection.

[prjemian]

done