Merge pull request #64 from Avogadro/more-work

Update initial tutorial
Avogadro · Nov 24, 2023 · ca3d14c · ca3d14c
2 parents b8c9b8c + 15e285b
commit ca3d14c
Show file tree

Hide file tree

Showing 24 changed files with 57 additions and 31 deletions.
diff --git a/source/_static/Ethanol.png b/source/_static/Ethanol.png
diff --git a/source/_static/FileImportByName.png b/source/_static/FileImportByName.png
diff --git a/source/_static/FileOpen.png b/source/_static/FileOpen.png
diff --git a/source/_static/IntroToAvogadro.png b/source/_static/IntroToAvogadro.png
diff --git a/source/_static/drag-to-build.png b/source/_static/drag-to-build.png
diff --git a/source/_static/draw-tool.png b/source/_static/draw-tool.png
diff --git a/source/_static/first-carbon.png b/source/_static/first-carbon.png
diff --git a/source/_static/pick-an-element.png b/source/_static/pick-an-element.png
diff --git a/source/_static/tutoria-co2-step2.png b/source/_static/tutoria-co2-step2.png
diff --git a/source/_static/tutorial-adjust-hydrogens.png b/source/_static/tutorial-adjust-hydrogens.png
diff --git a/source/_static/tutorial-bond-order.png b/source/_static/tutorial-bond-order.png
diff --git a/source/_static/tutorial-co2-step1.png b/source/_static/tutorial-co2-step1.png
diff --git a/source/_static/tutorial-co2-step3.png b/source/_static/tutorial-co2-step3.png
diff --git a/source/_static/tutorial-water.png b/source/_static/tutorial-water.png
diff --git a/source/conf.py b/source/conf.py
@@ -71,6 +71,9 @@
 # Make sure icons show in LaTeX / PDF output
 sd_fontawesome_latex = True
 
+locale_dirs = ['locale/']   # path is example but recommended.
+gettext_compact = 'docs'    # one file 
+
 myst_substitutions = {
   "release": release,
   "macurl": f"https://github.com/OpenChemistry/avogadrolibs/releases/download/{version}/Avogadro2-{version}-Darwin.dmg",

diff --git a/source/develop/scripts/index.md b/source/develop/scripts/index.md
@@ -19,11 +19,11 @@ Suggestions either for new types of scripts or new functions are always welcome.
 
 Scripts can either be installed manually, by dragging to the Avogadro window:
 
-![installing script](../_static/install-script.png)
+![installing script](../../_static/install-script.png)
 
 Scripts can also be installed from GitHub repositories through the "Download Plugins…" command:
 
-![plugin download](../_static/plugin-download.png)
+![plugin download](../../_static/plugin-download.png)
 
 ```{toctree}
 ---
@@ -32,8 +32,8 @@ hidden: true
 ---
 install
 interface
-commands
 charges
+commands
 energy
 formats
 generators

diff --git a/.../docs/display-types/coloring-molecules.md → ...play-types/coloring-part-of-a-molecule.md b/.../docs/display-types/coloring-molecules.md → ...play-types/coloring-part-of-a-molecule.md
diff --git a/source/docs/getting-started/drawing-molecules.md b/source/docs/getting-started/drawing-molecules.md
@@ -1,47 +1,54 @@
 # Drawing Molecules
 
-Molecules are built and edited with the draw tool.
+Molecules are built and edited with the [draw tool](draw-tool), which allows a "free-hand" sketch of new molecules.
 
-<figure><img src="../../_static/creating-a-molecule.png"></figure>
+```{tip} **New in 2.0**
+You can also use the new [template tool](template-tool) which makes it easier
+to attach functional groups or assemble inorganic / organometallic complexes.
+```
+
+![Screenshot of the draw tool](../../_static/draw-tool.png")
 
 Left clicking on the display will allow you to begin your journey into molecule creation. A left click will generate a carbon atom. A right click will delete the atom.
 
-<figure><img src="../../_static/d0340a40-b153-4710-a705-dd123fc862ad.png"></figure>
+![](../../_static/first-carbon.png")
 
 Left clicking the initial atom and dragging your mouse will generate a bond to another carbon atom.
 
-<figure><img src="../../_static/e5c67bd1-f903-4ede-a1a0-34a575d12e8b.png"></figure>
+![](../../_static/drag-to-build.png")
 
 Avogadro uses carbon as the default element. A different element can be selected through the "Element" drop down menu. Typing the atomic symbol (e.g., "O" for Oxygen, "A-s" for Arsenic) is a shortcut for changing the selected element.
 
-<figure><img src="../../_static/396b23b0-d64d-4fed-b606-92e8c7420994.png"></figure>
+![](../../_static/pick-an-element.png")
 
 Let's say you wanted to create water. You can either type in "O", or select "Oxygen (8)" from the drop down menu, and then click on the black display.
 
 Left clicking on an atom that has already been generated will also change the element. In this case, clicking on the initial carbon atom changed it into an oxygen atom.
 
-<figure><img src="../../_static/2e3013ad-c850-4827-96b5-d47738fe39d6.png"></figure>
+![](../../_static/tutorial-water.png")
 
 If the "Adjust Hydrogens" box is checked, hydrogen atoms in the molecule will be automatically adjusted to satisfy valency (as shown above).
 
-<figure><img src="../../_static/26534c23-d651-41d9-b936-e6852097a238.png"></figure>
+![](../../_static/tutorial-adjust-hydrogens.png")
 
-Bond order is changed through the "Bond Order" drop down menu, or by typing the numbers "1", "2", or "3". Bonds are added by left clicking on a bond that has already been created. Right clicking on a bond deletes the bond, and the atom it's bonded to.
+Bond order is changed through the "Bond Order" drop down menu, or by typing the numbers "1", "2", or "3". Bonds are added by left clicking on a bond that has already been created. Right clicking on a bond deletes the bond.
 
-<figure><img src="../../_static/a2495b0f-0ec4-4e27-84b9-42597f90a678.png"></figure>
+![](../../_static/tutorial-bond-order.png")
 
 ```{tip} **New in 2.0**
 The default bond order is "Automatic," and will adjust with the length of the bond.
 ```
 
 ### Creating Carbon Dioxide
 
-Begin drawing the "O-C-O" structure. After the structure is drawn, all you need to do is left click on the bonds. Left clicking on the bonds will create a double bond (shown below). 
+Begin drawing the "O-C-O" structure. After the structure is drawn, all you need to do is left click on the bonds. Left clicking on the bonds will create a double bond (shown below).
 
-<figure><img src="../../_static/7a8266c1-89ef-4dff-92a2-8eeb0b2b816f.png"></figure>
+![](../../_static/tutorial-co2-step1.png")
+![](../../_static/tutorial-co2-step2.png")
+![](../../_static/tutorial-co2-step3.png")
 
 Once you've created your molecule, you can optimize it's geometry through the extensions menu. Selecting the "Extensions" menu, and clicking "Optimize Geometry" will provide your molecule with proper bond lengths and angles.
 
-<figure><img src="../../_static/ada26872-ede7-4601-bd4e-d790c10ad614.png"></figure>
+![](../../_static/ada26872-ede7-4601-bd4e-d790c10ad614.png")
 
 You now know the basics of drawing a molecule in Avogadro!
diff --git a/source/docs/getting-started/index.md b/source/docs/getting-started/index.md
@@ -1,11 +1,16 @@
 # Getting Started
 
+* [Introduction](introduction)
+* [Drawing Molecules](drawing-molecules)
+* [Making Selections](making-selections)
+
 ```{toctree}
 ---
 caption: Getting Started
+hidden: true
 ---
 
 introduction
 drawing-molecules
 making-selections
-```
+```
diff --git a/source/docs/getting-started/introduction.md b/source/docs/getting-started/introduction.md
@@ -6,23 +6,28 @@ This manual was largely made on a Mac, but the interface should be very similar
 
 When you initially open Avogadro you will be presented with a screen such as the one shown below.
 
-<figure><img src="../../_static/015e6535-4871-43dd-99cb-d27fd0738a4e.png"></figure>
+![Screenshot of main Avogadro window indicating tools, display options, and drawing area](../../_static/IntroToAvogadro.png)
 
 ## Opening a File
 
-The first thing you will probably want to do is open a file and navigate around the molecule. To do this click on the `File` menu and select `Open...`.
+The first thing you will probably want to do is open a file and navigate around the molecule. To do this click on the `File` menu and select `Open...`
 
-<figure><img src="../../_static/opening-a-file.png"></figure>
+![Screenshot of File menu indicating Open menu item](../../_static/FileOpen.png)
 
-You can then look through the files on your disk and find an appropriate chemical file. Thanks to Open Babel, a large number of file types are supported including CML, XYZ, SDF, Mol2, PDB etc. Several example molecules are supplied with Avogadro.
+You can then look through the files on your disk and find an appropriate chemical file. Thanks to [Open Babel](https://openbabel.org/), a large number of file types are supported including CML, XYZ, SDF, Mol2, PDB etc.
 
-<figure><img src="../../_static/bdfc7544-6b58-4e14-85c3-892ba8260944.png"></figure>
+## Importing by Name
 
-The screen shot above shows the ethanol.cml file opened up and displayed using the default Ball and Stick display type. Notice that when a new file is opened Avogadro switches from the Draw Tool to the Navigate Tool, which allows you to view the molecule without editing it.
+Avogadro also offers support to download molecules from online sources. One of the most useful is the "Import" then "Download by Name..." which uses the [NIH Chemical Resolver](https://cactus.nci.nih.gov/chemical/structure).
+
+![Screenshot of the File menu indicating Import => Download By Name](../../_static/FileImportByName.png)
+
+The screen shot shows the an ethanol file opened up and displayed using the default Ball and Stick display type. Notice that when a new file is opened Avogadro switches from the Draw Tool to the Navigate Tool, which allows you to view the molecule without editing it.
+
+![Screenshot of Avogadro window after opening or importing ethanol molecule](../../_static/Ethanol.png)
 
 ## Navigation
 
 You can zoom in/out using the scroll wheel on your mouse or holding down the middle mouse button and moving the mouse cursor up/down. You can rotate the view by holding down the left mouse button and moving the mouse cursor. You can also translate the view by holding down the right mouse button and moving the mouse cursor.
 
 Note: if your mouse only has one or two buttons you can also use the modifier keys \(shift and control\) along with the left mouse button to perform actions where you would normally use the middle or right mouse buttons respectively.
-
diff --git a/source/docs/getting-started/making-selections.md b/source/docs/getting-started/making-selections.md
@@ -24,5 +24,4 @@ Clicking and dragging your cursor is another way molecules, or fragments of mole
 
 ![](../../_static/300264d3-31a2-4380-8c24-205fe639ae4d.png)
 
-More information on selections can be found in the "Tools" section.
-
+More information on selections can be found in the ["Tools" section](tools).
diff --git a/.../docs/optimizing-geometry/force-fields.md → ...ptimizing-geometry/molecular-mechanics.md b/.../docs/optimizing-geometry/force-fields.md → ...ptimizing-geometry/molecular-mechanics.md
diff --git a/source/docs/tools/draw-tool.md b/source/docs/tools/draw-tool.md
@@ -1,3 +1,5 @@
+(draw-tool)=
+
 # Draw Tool
 
 ## 1. Creating a Molecule

diff --git a/source/install/versions/v198.md b/source/install/versions/v198.md
@@ -2,29 +2,30 @@
 
 # Release Notes v1.98.0
 
-## Highlights (tldr)
+## 🌟 Highlights (tldr)
 
+- Integration with 3Dconnexion input devices on Mac and Windows
+  - Many thanks to 3Dconnexion and Patryk Skowroński (@pskowronskiTDx)
 - Improved rendering including ambient occlusion and real-time shadows
 - New template tool for assembly of inorganic complexes and ligands or attaching functional groups (e.g, "click to add phenyl group") (#1075)
 - [New forcefield framework](https://discuss.avogadro.cc/t/new-force-field-framework/4921?u=ghutchis) supporting external Python scripts (e.g., XTB, ASE, ANI-2x, etc.) (#1370)
 - Better perception of bond orders
-- Align tool #1364
+- Align tool (#1364)
 - Manual translate / rotate dialog
-- Integration with 3Dconnexion input devices on Mac and Windows
 - Fetch molecule names from PubChem, including markup
 - Commands to create centroid and center-of-mass points
 - Improved “fill unit cell” (#1375)
 - Preview images of insert molecule fragments and import crystals
 - Build improvements, including initial support for Qt6 and VTK9 fixes @cryos
 - Integrated Orca ouputfile support (from Orca-enhanced Avogadro) (#1326)
 - Add a generic compchem output reader (i.e., should automatically handle `.out` and `.log` files) (#1347)
-- Initial scripting support (e.g., used to generate preview images) (#1344)
+- Initial scripting support (e.g., used to generate preview images through a directory) (#1344)
 - Several updated toolbar icons
 
 ## ✨ Features
 
 - Reading Gaussian fchk vibrations when present @ghutchis (#1380)
-- Add support for atom labels (e.g., C1, C2, H1…) in the coordinate editor @ghutchis (#1362)
+- Add support for atom labels (e.g., C1, C2, H1…) in the coordinate editor using "L" symbol @ghutchis (#1362)
 - More pybind methods and properties @ghutchis (#1342)
 - Perceive bond orders when requested by Python scripts @ghutchis (#1211)
 - Support for color PLY format @spotenza2016 (#1177)
@@ -61,6 +62,10 @@
 
 ## 🐛 Bug Fixes
 
+- Add molden as a possible reader for generic `.out` files @ghutchis (#1409)
+- Fix a few UI / UX issues in the surface dialog @ghutchis (#1404)
+- Fix spurious "change layer" crash with the selection tool (#1406) (#1408)
+- Fix for reading imaginary vibrational frequencies in ORCA outputs. @dtelsing (#1398)
 - Ensure the VTK plot widget has a minimum size @cryos (#1231)
 - Add uncommon "ent" extension for PDB entries @ghutchis (#1144)
 - Put charge / spin in one line with two labels @ghutchis (#1143)
@@ -146,4 +151,4 @@
 
 ## Credits
 
-Thanks to many contributors, including: @DDinghoya, @DasJott, @Lisapple, @M3CG, @NorwayFun, @OfficerBrasidas, @SantosSi, @StefanBruens, @Surajjalpun2002, @WilliamBeltranC, @Xav83, @aerkiaga, @ahenao, @anmorgunov, @awvwgk, @balducci, @berquist, @comradekingu, @cryos, @dependabot, @dependabot[bot], @dominikflorjan, @dtelsing, @e-kwsm, @ghutchis, @github-actions, @grsousajunior, @hgokhanb, @koenr, @matterhorn103, @mck89, @milotype, @nbehrnd, @nicolazanna, @ovari, @pskowronskiTDx, @salif, @simmon-nplob, @spotenza2016, @tacitcoast, @tictactoe101, @trollixx, @vamsibarnala, @weblate, @yurivict, Ajith, Alejandro Díaz-Moscoso, Alex B, Eisuke Kawashima, FAN JI, Hugel, Jörg S, Kateryna Golovanvoa, Patryk Skowroński, Shusong Zhang, Translator, gallegonovato and victor dargallo
+Thanks to many contributors, including: @DDinghoya, @DasJott, @Lisapple, @M3CG, @NorwayFun, @OfficerBrasidas, @SantosSi, @StefanBruens, @Surajjalpun2002, @WilliamBeltranC, @Xav83, @adityaomar3, @aerkiaga, @ahenao, @anmorgunov, @awvwgk, @balducci, @berquist, @comradekingu, @cryos, @dependabot, @dominikflorjan, @dtelsing, @e-kwsm, @ghutchis, @github-actions, @grsousajunior, @hgokhanb, @koenr, @matterhorn103, @mck89, @milotype, @nbehrnd, @nicolazanna, @ovari, @pskowronskiTDx, @salif, @simmon-nplob, @spotenza2016, @tacitcoast, @tictactoe101, @trollixx, @vamsibarnala, @weblate, @yurivict, Ajith, Alejandro Díaz-Moscoso, Alex B, Eisuke Kawashima, FAN JI, Hugel, Jörg S, Kateryna Golovanvoa, Patryk Skowroński, Shusong Zhang, Weblate Translators, gallegonovato and victor dargallo
Original file line number	Diff line number	Diff line change
Expand Up		@@ -24,5 +24,4 @@ Clicking and dragging your cursor is another way molecules, or fragments of mole

		![](../../_static/300264d3-31a2-4380-8c24-205fe639ae4d.png)

		More information on selections can be found in the "Tools" section.

		More information on selections can be found in the ["Tools" section](tools).