new format for LAMMPS doc pages

Hi all - Richard Berger (JKU) created some formatting

tools that convert LAMMPS doc pages (doc/*.txt files)

into a nicer looking format than vanilla HTML. This

is via restructured text (rst) and Sphinx.

I’ve pushed them live to the web site a few minutes

ago, so people can take a look.

If you have feedback on pros/cons of this format versus

the old one (included in any tarball you’ve previously downloaded),

then reply to this email.

We’d like some feedback …

Steve

I really like the panel on the left, though it might be useful if the page for a given compute/pair style/fix/etc. showed up as a child of the corresponding category, rather than presenting a fully collapsed tree.

Also, why is the right margin fixed? This formatting makes poor use of horizontal space on my large display.

Anthony

Heh. Looks great. Will take some getting used to, the retro plain HTML-look had its “function-over-form” charms, but so far, this looks really neat. I like having the menu on the left, it makes the documentation feel more “explorable” for lack of a better word (übersichtlich, Axel’ll know what I mean ;))

Hi, Steve:

My suggestion would be, given the new layout, to “tear out” sections 3.5 through 3.13 (the “Commands” sections) and make them their own top-level unit. Right now, it’s hidden too deeply in the main hierarchy (even with the “Commands” links available).

Also, I agree with the width issue Anthony mentioned upthread. Right now, I lose an entire column of computes, because of the fixed-width cutoff.

—AEI

Thirding the issue with the fixed width cutoff. At the moment the list of possible keywords for commands at the top of the page gets wrapped awkwardly, even those there is a lot of whitespace to the right of the page.

Overall I like it a lot though, especially the highlighting of the notes/warnings for each command.

I have two suggestions, though I guess they would be a bit involved to implement:

  • A contents menu for each command, so that there are links at the top of the manual page to the “related commands”, “restrictions”, and “defaults” sections at the end of the page
  • Links in the syntax section so that keywords in the commands link to the relevant part of the text

Cheers,

Niall

Hi everyone,
sry, something is wrong with my thunderbird…
I personally find the text in the current (fixed width) form more comfortable to read.

As a suggestion for filling up the unused space:
would it be possible to include a table with mailing list questions for the currently opened chapter?
Say, I go to

Commands --> Pair_style potentials --> lj/cut

then on the right side, next to the documentation, there would be a list of questions (say the 5 most recent) about lj/cut.
Clicking on a question would then lead to the corresponding thread on sourceforge or lammps.sandia.gov/threads
This would maybe encourage people more to search through the mailing list first or to read what others have asked
(I know that this should be done anyway by everyone)

Paul

Hi everyone,
sry, something is wrong with my thunderbird...
I personally find the text in the current (fixed width) form more
comfortable to read.

As a suggestion for filling up the unused space:
would it be possible to include a table with mailing list questions for the
currently opened chapter?
Say, I go to

Commands --> Pair_style potentials --> lj/cut

then on the right side, next to the documentation, there would be a list of
questions (say the 5 most recent) about lj/cut.
Clicking on a question would then lead to the corresponding thread on
sourceforge or lammps.sandia.gov/threads
This would maybe encourage people more to search through the mailing list
first or to read what others have asked
(I know that this should be done anyway by everyone)

apart from the fact that what you are asking for is extremely time
consuming and impractical (who's going to keep it up to date and how?
there is no way to do this automatically),
searching through the mailing list archives is really only a crutch.
the discussions not always hit the right answer right away (for a
variety of reasons) and people that have problems figuring out stuff
from the documentation have even bigger problems reading threads in
the mailing list archives correctly. i know this very well, because i
get frequent e-mails from people that ask me how i solved "my" problem
with a reference to a mailing list discussion, where i responded to
*somebody else's* problem. secondly, if there is good and bad advice
been given in the same thread, murphy's law dictates that people will
follow the bad advice.

thus a *much* better approach would be to have a properly edited FAQ.
i.e. people would go over the mailing list archive, say, once a month
and then look at frequent/common questions and then try to generalize
them and update a FAQ document accordingly (or the reference manual
where appropriate). this would be a fantastic way for all of those to
give back and contribute to the LAMMPS effort (and learn themselves a
lot). i have done something similar many years back for the CPMD code
and turned out to be extremely helpful to me and to the CPMD user
community.

due to technical issues, this FAQ would have to be hosted outside of
sandia, but we can put it somewhere under the lammps.org domain and
then give access to people willing to help out (starting with writing
an extensive summary about "lost atoms" and how to deal with them, i
would suggest. :wink: ).

axel.

Hi ppl,

Thirding the issue with the fixed width cutoff. At the moment the list
of possible keywords for commands at the top of the page gets wrapped
awkwardly, even those there is a lot of whitespace to the right of the page.

This came from the original read-the-docs theme. I've now changed the CSS setting. Next time Steve rebuilds the content area will fill the entire screen.

Overall I like it a lot though, especially the highlighting of the
notes/warnings for each command.

Happy to hear that. My conversion tool does some semantic replacements which I thought were useful.

I have two suggestions, though I guess they would be a bit involved to
implement:

- A contents menu for each command, so that there are links at the top
of the manual page to the "related commands", "restrictions", and
"defaults" sections at the end of the page

So basically a local TOC for a command page? Yes, I could generate those.

- Links in the syntax section so that keywords in the commands link to
the relevant part of the text

Links are already functional inside of the syntax region, but they have to be added by people writing the docs. Automation can only do so much. If there is a pattern, it can be detected and acted upon.

Keep those suggestions coming.

Cheers,
Richard

one nice thing about the sphinx output is, that it makes dead internal
links easily visible.
e.g. we need the patches in the command and compute overviews. if
people spot more of those, just let us know...

axel.

diff --git a/doc/Section_commands.txt b/doc/Section_commands.txt
index e8aead9..6e3f34c 100644
--- a/doc/Section_commands.txt
+++ b/doc/Section_commands.txt
@@ -697,9 +697,9 @@ KOKKOS, o = USER-OMP, t = OPT.
"reduce"_compute_reduce.html,
"reduce/region"_compute_reduce.html,
"slice"_compute_slice.html,
-"sna/atom"_compute_sna.html,
-"snad/atom"_compute_sna.html,
-"snav/atom"_compute_sna.html,
+"sna/atom"_compute_sna_atom.html,
+"snad/atom"_compute_sna_atom.html,
+"snav/atom"_compute_sna_atom.html,
"stress/atom"_compute_stress_atom.html,
"temp (c)"_compute_temp.html,
"temp/asphere"_compute_temp_asphere.html,
diff --git a/doc/compute.txt b/doc/compute.txt
index 0872ded..279ea04 100644
--- a/doc/compute.txt
+++ b/doc/compute.txt
@@ -218,9 +218,9 @@ page"_Section_commands.html#cmd_5.
"reduce"_compute_reduce.html - combine per-atom quantities into a
single global value
"reduce/region"_compute_reduce.html - same as compute reduce, within a region
"slice"_compute_slice.html - extract values from global vector or array
-"sna/atom"_compute_sna.html - calculate bispectrum coefficients for each atom
-"snad/atom"_compute_sna.html - derivative of bispectrum coefficients
for each atom
-"snav/atom"_compute_sna.html - virial contribution from bispectrum
coefficients for each atom
+"sna/atom"_compute_sna_atom.html - calculate bispectrum coefficients
for each atom
+"snad/atom"_compute_sna_atom.html - derivative of bispectrum
coefficients for each atom
+"snav/atom"_compute_sna_atom.html - virial contribution from
bispectrum coefficients for each atom
"stress/atom"_compute_stress_atom.html - stress tensor for each atom
"temp"_compute_temp.html - temperature of group of atoms
"temp/asphere"_compute_temp_asphere.html - temperature of aspherical particles

Btw we could think about adding additional TOCs to group things in the left bar together. See:

https://read-the-docs.readthedocs.org/en/latest/getting_started.html

They're grouping "User Documentation", "Feature Documentation", "Developer Documentation", etc.

I'm not talking about following this scheme, but using the grouping feature.

Cheers,
Richard