From d418d7639b75647b51110701ba7ac1721e38351e Mon Sep 17 00:00:00 2001 From: Kyle Shores Date: Mon, 12 Aug 2024 11:49:26 -0500 Subject: [PATCH] setting up new documentation --- doc/source/_static/MusicBox.png | Bin 2287 -> 0 bytes doc/source/_static/MusicBox.svg | 1 + doc/source/_static/custom.css | 7 ++ doc/source/_static/index_api.svg | 97 +++++++++++++++++++ doc/source/_static/index_contribute.svg | 76 +++++++++++++++ doc/source/_static/index_getting_started.svg | 66 +++++++++++++ doc/source/_static/index_user_guide.svg | 67 +++++++++++++ doc/source/{ => api}/acom_music_box.rst | 4 +- doc/source/{modules.rst => api/index.rst} | 5 +- doc/source/conf.py | 16 ++- doc/source/contributing/index.rst | 3 + doc/source/getting_started.rst | 3 + doc/source/index.rst | 53 +++++++++- doc/source/user_guide/index.rst | 3 + 14 files changed, 387 insertions(+), 14 deletions(-) delete mode 100644 doc/source/_static/MusicBox.png create mode 100644 doc/source/_static/MusicBox.svg create mode 100644 doc/source/_static/custom.css create mode 100644 doc/source/_static/index_api.svg create mode 100644 doc/source/_static/index_contribute.svg create mode 100644 doc/source/_static/index_getting_started.svg create mode 100644 doc/source/_static/index_user_guide.svg rename doc/source/{ => api}/acom_music_box.rst (98%) rename doc/source/{modules.rst => api/index.rst} (62%) create mode 100644 doc/source/contributing/index.rst create mode 100644 doc/source/getting_started.rst create mode 100644 doc/source/user_guide/index.rst diff --git a/doc/source/_static/MusicBox.png b/doc/source/_static/MusicBox.png deleted file mode 100644 index 19aea527248941f59013251fb3255e66472bbf85..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 2287 zcmVA_-_%A+d;xDA-7Ck%yI+1qGx85nVz=9%T_I zMM%Zk7KBxn@~A)w5i9`#g~VDO3JM6K21!C7@uGxWZ*u3}x%bYTbNT}li3Dh}dVbC9 z`S!QJv**m7y@`|(ty#<7C!UUOx>{iZv3g7%_pl7LhKIC9z``|&9pl=FBCjWs>G4>S zF?n2a3>kf&^tF_Ww$$Od{2u8c%lnZT)Utv>wZJsp1)S3?qTrLl!z8Pvd@ahrW4U(^ z_Ije5yq?JW9&hAPZ=91J?+OY}yz_;}W9?*2W=mi!0nShrz7bin?na#da|Zg2&3?fQ z>ILDDHq{InN+_hS%X_l=>**uv%7Ui8#xxDp;mQ;OYz1&a*f_KCFuC+xSV1LXGS z+AF-^`^d#bGi>eHv&9W zc$6fxN`R~P^e$A92Sb*Aj~Q}3c&2!BdDn+VJZze-%uq<*9jMoehR*62*MPSyEk6|2 zdxe6=4lAg4j#4B6fUt3>@CZr1<|d_-AcV{SkOZb1iaRNp7zt;TPJ_k@$JxbWJX3OU z(WP0h$Hm!y@Oq+KDnHzIGBLTsO2bVO8MQ+-)q$;nn#knzd*h4TF5c%zNq9W~sp?Q4 z8HpL(M)>QKc=ODc_y9nOls_I$BBew^oA#&w{N~$@?{vw$>F^nSmW7Y6o=JL7Z^JC- zh;W44Fd_+FEihI3KF(jf{H;d$vvOqrG44&f-YCz`Us06w(_IQ7ap|HDRh8v< zuV_oC;_EM;lTxk)emI0oWk|gvqtRi)Gcz#%_b+t@Rzn_tEuf{pP)i{TtgwEUbK&&Z zoSbKG>5<;M5pNi79t>+0lrZ&5o~G+Ee$@D>?nN_m-Xw(7N-2woloIU|Z$7jAscqmL*XF&)l5|aPJU>tW=E2bEFHU$p9`CXD zj#l*sfW!NX@$R+_0033h(6d(-9(&?x5UL;?GR5!*dY%lK!QRatLP7|}Pnkglqle=9 z&rOURd$ovav_xFme{}SOXFFUO{93E}dnag_% z)7=wpx|MDBRaZ7Xi&$X`0KZDW-W^+DSz$p4!Gx)~Bv!F6tSaoFQ+ulK=y8)048wpF zLKYRSySj)G(uD8OyEP|YnR>P?Z~TS66`!|VGHB??%h@?s!OxbJeki4sSCP~OYEig; z6@79_F8U4p73sG6FDX85mU+$6l%ZqR008!E-%QS*ExRf{RrSP%>w&)VDa*|;C6f9IJVrd`n6gBE1GN^ zL?evkNheg^VEf)*1Cu)6wY#%jabkwIU1`O>af|0p0|4CCwY!o%`0@J)A-$UaoTv~^ zYM-+OYhMQd7={Y~u%qxF#8-XpWdKduFA2gFM(!uVHm|gQTUxOoXzHC}F}5eAPioc0 z@6I;9x^CTj0zhi>bs(kZIIVZzjBPvK5#Rf30RVO^hK*}ingCWc<07G}!=<9PxzcDy zf_+Zyd2d6-@v5ZHip%%j|KPC3c;EXk0f4{Ren4oflb}4)^k2yM2Ez*Ok^kt%(3BqT!G8hkFv%Q~*c@ zfaH`kB&VcZ#a$QhW6?`F#8*}MJ1J#^0f1$N<;FMu3IO=*lY`(j-^@q%)Li|=h25j| z9iEYYpKKF?W3FDWPGoJOU%9(wcuG%wj0PY7rHc{(94_?++fSESUx%v7a(w#HzdsL| z!Rb=U;>+SM_XGC;@LYjEfqC=1G)8x*f_-N&^>HN>hl1~rEJ=|U$-kJvu7tT7+Vxh zZ_}hYOtDD`<;qtIr}r=$J$!HEo@>Ci8@ec8M0sCn^Dnr=rwCg}5wVM-R2?BdU3$&# z__}{JxpZlr<08LysQ4g8?ENt+=5d7|=88a+aNdAR9P_7+iq57fhB}AnY&>)|n=(>P z4Q=i9g5OX80LZ*N$H`ytj7^=zoH;8T%D=Livs)UN-+)mJI-jVlm};a8)f81_bT`#l z0$j>}Zp7cB!Gz7udz5iyqr%x<=8(af(9?;-B@^tFjEbGY;n^Z;|5gfFCL{ct+Fg0| z|5pJ3pwFJ4PHeVQk;>1QL$@%_BooRg#;H%n_z>T^+@mewYt?W{W-aWfaZ<#DlF1w@ znPkT)FSU3$ZIu83ATwurG!egA1(jZ^=Y0Fhi>(^Z{|n&% \ No newline at end of file diff --git a/doc/source/_static/custom.css b/doc/source/_static/custom.css new file mode 100644 index 00000000..cee0af4b --- /dev/null +++ b/doc/source/_static/custom.css @@ -0,0 +1,7 @@ +.sd-card-img-top { + width: 33% !important; + display: block; + margin-left: auto; + margin-right: auto; + margin-top: 10px; +} diff --git a/doc/source/_static/index_api.svg b/doc/source/_static/index_api.svg new file mode 100644 index 00000000..900ebdd7 --- /dev/null +++ b/doc/source/_static/index_api.svg @@ -0,0 +1,97 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/source/_static/index_contribute.svg b/doc/source/_static/index_contribute.svg new file mode 100644 index 00000000..d8cf8054 --- /dev/null +++ b/doc/source/_static/index_contribute.svg @@ -0,0 +1,76 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + \ No newline at end of file diff --git a/doc/source/_static/index_getting_started.svg b/doc/source/_static/index_getting_started.svg new file mode 100644 index 00000000..2aa51ac0 --- /dev/null +++ b/doc/source/_static/index_getting_started.svg @@ -0,0 +1,66 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + \ No newline at end of file diff --git a/doc/source/_static/index_user_guide.svg b/doc/source/_static/index_user_guide.svg new file mode 100644 index 00000000..5d776b32 --- /dev/null +++ b/doc/source/_static/index_user_guide.svg @@ -0,0 +1,67 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + \ No newline at end of file diff --git a/doc/source/acom_music_box.rst b/doc/source/api/acom_music_box.rst similarity index 98% rename from doc/source/acom_music_box.rst rename to doc/source/api/acom_music_box.rst index 13ad4619..176c4635 100644 --- a/doc/source/acom_music_box.rst +++ b/doc/source/api/acom_music_box.rst @@ -1,5 +1,5 @@ -acom\_music\_box package -======================== +MusicBox +======== Submodules ---------- diff --git a/doc/source/modules.rst b/doc/source/api/index.rst similarity index 62% rename from doc/source/modules.rst rename to doc/source/api/index.rst index 028d78a5..3e09626f 100644 --- a/doc/source/modules.rst +++ b/doc/source/api/index.rst @@ -1,5 +1,6 @@ -acom_music_box -============== +### +API +### .. toctree:: :maxdepth: 4 diff --git a/doc/source/conf.py b/doc/source/conf.py index e240a0d8..6985fb1f 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -1,6 +1,7 @@ import sys import os import datetime +import acom_music_box sys.path.insert(0, os.path.abspath('..')) # Configuration file for the Sphinx documentation builder. @@ -11,7 +12,8 @@ # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information -project = 'Music Box' +release = acom_music_box.__version__ +project = f'Music Box ({release})' copyright = f'2024-{datetime.datetime.now().year}, NCAR/UCAR' author = 'NCAR/UCAR' @@ -27,8 +29,6 @@ templates_path = ['_templates'] exclude_patterns = [] - - # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output @@ -36,11 +36,17 @@ html_theme = 'pydata_sphinx_theme' html_theme_options = { + "navbar_start": ["navbar-logo", "version-switcher"], "external_links": [], "github_url": "https://github.com/NCAR/music-box", - "navbar_end": ["version-switcher", "navbar-icon-links"], + "navbar_end": ["theme-switcher", "navbar-icon-links"], "pygment_light_style": "tango", "pygment_dark_style": "monokai" } -html_favicon = '_static/favicon.png' \ No newline at end of file +html_css_files = [ + 'custom.css' +] + +html_favicon = '_static/favicon.png' +html_logo = "_static/MusicBox.svg" \ No newline at end of file diff --git a/doc/source/contributing/index.rst b/doc/source/contributing/index.rst new file mode 100644 index 00000000..6bfafddf --- /dev/null +++ b/doc/source/contributing/index.rst @@ -0,0 +1,3 @@ +############ +Contributing +############ \ No newline at end of file diff --git a/doc/source/getting_started.rst b/doc/source/getting_started.rst new file mode 100644 index 00000000..64446728 --- /dev/null +++ b/doc/source/getting_started.rst @@ -0,0 +1,3 @@ +############### +Getting Started +############### \ No newline at end of file diff --git a/doc/source/index.rst b/doc/source/index.rst index d0d926ea..29b41629 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -3,20 +3,63 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. +.. +.. # (over and under) for module headings +.. = for sections +.. - for subsections +.. ^ for subsubsections +.. ~ for subsubsubsections +.. " for paragraphs + +##################################### Welcome to Music Box's documentation! -========================================== +##################################### + +.. grid:: 1 1 2 2 + :gutter: 2 + + .. grid-item-card:: Getting started + :img-top: _static/index_getting_started.svg + :link: getting_started + :link-type: doc + + Check out the getting started guide to install music box. + + .. grid-item-card:: User guide + :img-top: _static/index_user_guide.svg + :link: user_guide/index + :link-type: doc + + Learn how to configure music box for your mechanisms here! + + .. grid-item-card:: API reference + :img-top: _static/index_api.svg + :link: api/index + :link-type: doc + + The source code for music box is heavily documented. This reference will help you understand the internals of music box. + + .. grid-item-card:: Contributors guide + :img-top: _static/index_contribute.svg + :link: contributing/index + :link-type: doc + + If you'd like to contribute some new science code or update the docs, + checkout the contributors guide! + .. toctree:: :maxdepth: 2 :caption: Contents: - modules - - + getting_started + user_guide/index + api/index + contributing/index + citing_and_bibliography/index Indices and tables ================== * :ref:`genindex` -* :ref:`modindex` * :ref:`search` diff --git a/doc/source/user_guide/index.rst b/doc/source/user_guide/index.rst new file mode 100644 index 00000000..7875f3ca --- /dev/null +++ b/doc/source/user_guide/index.rst @@ -0,0 +1,3 @@ +########## +User Guide +########## \ No newline at end of file