Niceties and improved documentation (#80)

Author: fsoubelet

.github/workflows/documentation.yml

@@ -69,45 +69,57 @@ jobs:
       # Forcing several successive builds here and hoping it works out (sphinx-gallery 
       # checks for the existence of already built examples to avoid re-running them, so
       # once the gallery is built successive builds will just re-generate the html, very quickly)
-      - name: Build documentation (1/7)
+      - name: Build documentation (1/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
-      - name: Build documentation (2/7)
+      - name: Build documentation (2/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
-      - name: Build documentation (3/7)
+      - name: Build documentation (3/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
-      - name: Build documentation (4/7)
+      - name: Build documentation (4/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
-      - name: Build documentation (5/7)
+      - name: Build documentation (5/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
-      - name: Build documentation (6/7)
+      - name: Build documentation (6/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
-      - name: Build documentation (7/7)
+      - name: Build documentation (7/10)
+        continue-on-error: true
+        run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
+
+      - name: Build documentation (8/10)
+        continue-on-error: true
+        run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
+
+      - name: Build documentation (9/10)
+        continue-on-error: true
+        run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
+
+      - name: Build documentation (10/10)
         continue-on-error: true
         run: poetry run python -m sphinx -v -b html docs doc_build -d doc_build
 
       # Upload artifacts if in PR so reviewers can have a quick look without building documentation from the branch locally
       - name: Upload build artifacts
         uses: actions/upload-artifact@v2
-        if: ${{ success() }} && github.event_name == 'pull_request'  # only for pushes in PR
+        if: success() && github.event_name == 'pull_request'  # only for pushes in PR
         with:
           name: site-build
           path: doc_build
           retention-days: 7
 
       - name: Upload documentation to gh-pages
-        if: ${{ success() }} && github.ref == 'refs/heads/master'  # only for pushes to master
+        if: success() && github.ref == 'refs/heads/master'  # only for pushes to master
         uses: JamesIves/[email protected]
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

docs/conf.py

@@ -52,6 +52,8 @@ def __call__(self, *args, **kwargs):
 copyright = f"2019, {pyhdtoolkit.__author__}"
 author = pyhdtoolkit.__author__
 
+rst_prolog = f""":github_url: {pyhdtoolkit.__url__}"""
+
 # The full version, including alpha/beta/rc tags
 version = pyhdtoolkit.__version__
 release = pyhdtoolkit.__version__
@@ -517,7 +519,7 @@ def __call__(self, *args, **kwargs):
 # use in refs e.g:
 # :ref:`comparison manual <python:comparisons>`
 intersphinx_mapping = {
-    "python": ("https://docs.python.org/", None),
+    "python": ("https://docs.python.org/3/", None),
     "numpy": ("https://numpy.org/doc/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "matplotlib": ("https://matplotlib.org/stable/", None),

docs/references.bib

@@ -1,84 +1,93 @@
 @article{Boumal:NPS:2016,
-	title        = {Nonconvex Phase Synchronization},
-	author       = {Boumal, Nicolas},
-	year         = 2016,
-	journal      = {SIAM Journal on Optimization},
-	volume       = 26,
-	number       = 4,
-	pages        = {2355--2377},
-	doi          = {10.1137/16M105808X},
-	url          = {https://doi.org/10.1137/16M105808X}
+  author  = {Boumal, Nicolas},
+  doi     = {10.1137/16M105808X},
+  journal = {SIAM Journal on Optimization},
+  number  = 4,
+  pages   = {2355--2377},
+  title   = {Nonconvex Phase Synchronization},
+  url     = {https://doi.org/10.1137/16M105808X},
+  volume  = 26,
+  year    = 2016
 }
 @article{Miyamoto:ACD:2008,
-	title        = {Parametrization of the driven betatron oscillation},
-	author       = {Miyamoto, R. and Kopp, S. E. and Jansson, A. and Syphers, M. J.},
-	year         = 2008,
-	month        = {Aug},
-	journal      = {Phys. Rev. ST Accel. Beams},
-	publisher    = {American Physical Society},
-	volume       = 11,
-	pages        = {084002},
-	doi          = {10.1103/PhysRevSTAB.11.084002},
-	url          = {https://link.aps.org/doi/10.1103/PhysRevSTAB.11.084002},
-	issue        = 8,
-	numpages     = 8
+  author    = {Miyamoto, R. and Kopp, S. E. and Jansson, A. and Syphers, M. J.},
+  doi       = {10.1103/PhysRevSTAB.11.084002},
+  issue     = 8,
+  journal   = {Phys. Rev. ST Accel. Beams},
+  month     = {Aug},
+  numpages  = 8,
+  pages     = {084002},
+  publisher = {American Physical Society},
+  title     = {Parametrization of the driven betatron oscillation},
+  url       = {https://link.aps.org/doi/10.1103/PhysRevSTAB.11.084002},
+  volume    = 11,
+  year      = 2008
 }
 
 @article{Tomas:ACDAdiabaticity:2005,
-	title        = {Adiabaticity of the ramping process of an ac dipole},
-	author       = {Tom\'as, R.},
-	year         = 2005,
-	month        = {Feb},
-	journal      = {Phys. Rev. ST Accel. Beams},
-	publisher    = {American Physical Society},
-	volume       = 8,
-	pages        = {024401},
-	doi          = {10.1103/PhysRevSTAB.8.024401},
-	url          = {https://link.aps.org/doi/10.1103/PhysRevSTAB.8.024401},
-	issue        = 2,
-	numpages     = 7
+  author    = {Tom\'as, R.},
+  doi       = {10.1103/PhysRevSTAB.8.024401},
+  issue     = 2,
+  journal   = {Phys. Rev. ST Accel. Beams},
+  month     = {Feb},
+  numpages  = 7,
+  pages     = {024401},
+  publisher = {American Physical Society},
+  title     = {Adiabaticity of the ramping process of an ac dipole},
+  url       = {https://link.aps.org/doi/10.1103/PhysRevSTAB.8.024401},
+  volume    = 8,
+  year      = 2005
 }
 
 @inproceedings{Ripken:optics:1989,
-	title        = {Methods of beam optics},
-	author       = {Willeke, F. and Ripken, G.},
-	year         = 1989,
-	booktitle    = {{AIP} {Conference} {Proceedings}},
-	publisher    = {AIP},
-	address      = {FERMILAB/ CORNELL UNIVERSITY, USA},
-	volume       = 184,
-	pages        = {758--819},
-	doi          = {10.1063/1.38050},
-	url          = {http://aip.scitation.org/doi/abs/10.1063/1.38050},
-	note         = {ISSN: 0094243X},
-	language     = {en}
+  address   = {FERMILAB/ CORNELL UNIVERSITY, USA},
+  author    = {Willeke, F. and Ripken, G.},
+  booktitle = {{AIP} {Conference} {Proceedings}},
+  doi       = {10.1063/1.38050},
+  language  = {en},
+  note      = {ISSN: 0094243X},
+  pages     = {758--819},
+  publisher = {AIP},
+  title     = {Methods of beam optics},
+  url       = {http://aip.scitation.org/doi/abs/10.1063/1.38050},
+  volume    = 184,
+  year      = 1989
 }
 
 @article{Lebedev:coupling:2010,
-	title        = {Betatron {Motion} with {Coupling} of {Horizontal} and {Vertical} {Degrees} of {Freedom}},
-	author       = {Lebedev, V A and Bogacz, S A},
-	year         = 2010,
-	journal      = {Journal of Instrumentation},
-	pages        = 24,
-	doi          = {10.1088/1748-0221/5/10/P10010},
-	url          = {https://arxiv.org/ftp/arxiv/papers/1207/1207.5526.pdf},
-	language     = {en}
+  author   = {Lebedev, V A and Bogacz, S A},
+  doi      = {10.1088/1748-0221/5/10/P10010},
+  journal  = {Journal of Instrumentation},
+  language = {en},
+  pages    = 24,
+  title    = {Betatron {Motion} with {Coupling} of {Horizontal} and {Vertical} {Degrees} of {Freedom}},
+  url      = {https://arxiv.org/ftp/arxiv/papers/1207/1207.5526.pdf},
+  year     = 2010
 }
 
 @book{Strang:linalg:1980,
-	title        = {Linear Algebra and Its Applications},
-	author       = {G. Strang},
-	year         = 1980,
-	publisher    = {Academic Press, Inc.},
-	address      = {Orlando, FL},
-	isbn         = {0534422004}
+  address   = {Orlando, FL},
+  author    = {G. Strang},
+  isbn      = {0534422004},
+  publisher = {Academic Press, Inc.},
+  title     = {Linear Algebra and Its Applications},
+  year      = 1980
 }
 
 @misc{Tomas:CASImperfections:2018,
-	title        = {Imperfections and corrections},
-	author       = {R. Tomás and X. Buffat and J. Coello and E. Fol and L. Malina},
-	year         = 2018,
-	eprint       = {2006.10661},
-	archiveprefix = {arXiv},
-	primaryclass = {physics.acc-ph}
+  archiveprefix = {arXiv},
+  author        = {R. Tomás and X. Buffat and J. Coello and E. Fol and L. Malina},
+  eprint        = {2006.10661},
+  primaryclass  = {physics.acc-ph},
+  title         = {Imperfections and corrections},
+  year          = 2018
+}
+
+@article{Carlier:AccuracyFeasibilityMeasurement2017,
+  author       = {Carlier, F. and Tomás, R.},
+  doi          = {10.1103/PhysRevAccelBeams.20.011005},
+  journal      = {Phys. Rev. ST Accel. Beams},
+  journaltitle = {Physical Review Accelerators and Beams},
+  title        = {Accuracy and Feasibility of the β * Measurement for {{LHC}} and {{High Luminosity LHC}} Using k Modulation},
+  year         = {2017}
 }

docs/release.rst

@@ -3,6 +3,36 @@ Release Notes
 
 The full list of releases can be found in the Github repository's `releases page <https://github.com/fsoubelet/PyhDToolkit/releases>`_.
 
+.. _release_0.18.0:
+
+0.18.0
+------
+
+Enhancements
+~~~~~~~~~~~~
+
+* The `pyhdtoolkit.utils._misc` module has a new function,  `~pyhdtoolkit.utils._misc.add_markers_around_lhc_ip` to add `MAD-X` markers around a given IP in order to increase the resolution of the TWISS calls in the IP vicinity.
+* The `pyhdtoolkit.utils._misc` module has a new function,  `~pyhdtoolkit.utils._misc.get_lhc_ips_positions`, to determine the longitudinal position (S variable) of LHC IPs from a dataframe.
+* The `pyhdtoolkit.utils._misc` module has a new function,  `~pyhdtoolkit.utils._misc.draw_ip_locations`, to add labels with the location of LHC IPs to a given `~matplotlib.axes.Axes` object.
+* The `LHC Rigid Waist Shift` gallery has been improved, and now shows a visualization of the waist shift and two ways to calculate its value.
+
+Bug Fixes
+~~~~~~~~~
+
+* The `~pyhdtoolkit.cpymadtools.orbit.lhc_orbit_variables` function does not return a wrong `on_phi_IR5` variable anymore.
+
+Maintenance
+~~~~~~~~~~~
+
+* The dependency on `matplotlib` has been pinned to `<3.5` to avoid issues with the documentation plot style, to be fixed later on. 
+* The bibliography file for the package's documentation has been cleaned up.
+* The Github icon in the documentation pages now redirects to the proper pages.
+* The documentation for the `~pyhdtoolkit.maths.nonconvex_phase_sync` has been improved.
+* Some additional files necessary for the documentation additions are now included in the repo, but not the package.
+
+See `v0.18.0 release notes on GitHub <https://github.com/fsoubelet/PyhDToolkit/releases/tag/0.18.0>`_ and the `full changes since v0.17.0 <https://github.com/fsoubelet/PyhDToolkit/compare/0.17.0...0.18.0>`_.
+
+
 .. _release_0.17.0:
 
 0.17.0