Fix table formatting in TechnicalIntroduction.rst

[cary-ilm]

Tables currently implemented as grid tables should be converted to list-table, which handles left-justification of text:

• https://openexr.com/en/latest/TechnicalIntroduction.html#levels-and-level-modes
• https://openexr.com/en/latest/TechnicalIntroduction.html#tiled-image

This task requires some basic familiarity with reStructuredText and sphinx but the concepts are easy to pick up from other examples. See Building the Website for how to test the formatting.

[ghost]

I'm interested in looking at this one for the dev day.

[cary-ilm]

Thank you! Let us know, here or on the OpenEXR or Dev Days slack, if you need any help with getting things built. The install instructions should step you through installing the required dependencies, for the library and for the website, but if anything there is confusing, we should straighten that out.

[ghost]

Sweet. Many thanks for the extra info!

[ghost]

I'm not clear what a useful branch name would be for documentation work. The Contributing instructions say to create a local branch using the format feature/ or bugfix/. Would docs/table-formatting-TechnicalIntroduction be an acceptable name for a branch for this issue? Happy to follow any further guidance if that guess is off-base.

[peterhillman]

That sounds reasonable. The branch name becomes less relevant once the changes are merged into the main branch. The commit messages and title of the PR stick around longer, so it's more important to make those clear.

[ghost]

Hey, I'm finding the install instructions a bit confusing. The part with $builddir, $srcdir and $installdir alludes to things I need to consider, but I don't have enough information to come to any conclusions about whether I'm making the right decisions about which directories to use.

[cary-ilm]

Yeah, that's confusing but I came up empty on a better way to explain it. There are three directories involved in the build process. The "source" directory is where the source is, the top level of the repo you've downloaded from GitHub. This should be the directory with the README.md file in it. The documentation refers to this as $srcdir.

Next is the "build" directory, where CMake will put the files it generates, and make will put the compiled .o files, etc. You need to create this directory from scratch, and it can go anywhere. Personally, I have a ~/build directory and inside of there I have subdirectories for OpenEXR, for Imath, for OpenVDB, for any software package I'm going to build. The documentation refers to that as the $builddir.

Finally, when you're done building the OpenEXR libraries and you want to link another application against those libraries, you want the libraries installed into a directory that's outside of the build directory. This is the "install" directory and it too can go anywhere. This directory gets populated when you do "make install", or "cmake --target install". it You might choose ~/install/openexr. The documentation refers to this as $installdir. If you're just doing internal development, or working on the website, you may not need this directory at all.

The names of these things can be anything you want. And as @peterhillman says, the name of your branch doesn't matter to anyone but you. The best practice is to do development in small chunks, with each chunk going into a branch. Once you've submitted the work on that branch as a PR, you delete the branch. These sorts of branches don't live very long.

[ghost]

Hi Cary, many thanks for that explanation. I think the command I ended up with used a default install directory in the end - though I haven't yet worked out where that might have been.
Unfortunately I'm still not able to build the website, and it's too close to the end of the day to tackle the rest of the process at this point. The RST change is easy enough (took me about 10 minutes), but I can't submit a change if I can't build the project to check for mistakes.
If anyone else wants to pick up this issue, please do, I'm not in a position to do any further work here.