diff --git a/_static/pyos.css b/_static/pyos.css index 6bfeb1af7..a82b45200 100644 --- a/_static/pyos.css +++ b/_static/pyos.css @@ -36,9 +36,9 @@ figure { figcaption { font-size: .9em; font-weight: bold; - } +} + .admonition p { - font-size: 1.1em; - font-weight: bold; - } + font-size: 1em; +} diff --git a/code-style-structure/intro.md b/code-style-structure/intro.md deleted file mode 100644 index f2e918b7d..000000000 --- a/code-style-structure/intro.md +++ /dev/null @@ -1,4 +0,0 @@ -# Code style and structure - - -Under development diff --git a/conf.py b/conf.py index 562d5c3c4..921251bb0 100644 --- a/conf.py +++ b/conf.py @@ -18,8 +18,8 @@ # -- Project information ----------------------------------------------------- project = 'python-package-guide' -copyright = '2022, pyOpenSci' -author = 'Leah Wasser' +copyright = '2023, pyOpenSci' +author = 'pyOpenSci Community' # The full version, including alpha/beta/rc tags release = '0.1' @@ -44,22 +44,57 @@ "colon_fence", "deflist", ] -#myst_heading_anchors = 3 +myst_heading_anchors = 3 + +# For generating sitemap +html_baseurl = 'https://www.pyopensci.org/software-peer-review/' # Link to our repo for easy PR/ editing html_theme_options = { - "source_repository": "https://github.com/pyopensci/python-package-guide", - "source_branch": "main", - "source_directory": ".", - # "repository_url": "https://github.com/pyopensci/python-package-guide", - # "use_repository_button": True, - #"google_analytics_id": "UA-141260825-1", - #"show_toc_level": 1, - #"toc_title": "On this page", -# "external_links": [ -# {"pyOpenSci Website": "link-one-name", "url": "https://www.pyopensci.org"} -# ], - "announcement": "🚧 UNDER CONSTRUCTION: this guide is under heavy construction right now. 🚧" + "announcement": "🚧 This guide is currently under heavy construction 🚧 ", + "external_links": [ + { + "url": "https://www.pyopensci.org", + "name": "pyOpenSci Website", + }, + { + "url": "https://www.pyopensci.org/python-package-guide", + "name": "Python Packaging Guide", + }, + { + "url": "https://pyopensci.org/governance", + "name": "Governance", + }, + ], + "icon_links": [ + { + "name": "Mastodon", + "url": "https://fosstodon.org/@pyOpenSci", + "icon": "fa-brands fa-mastodon", + }, + ], + "logo": { + "text": "Python Package Guide", + "image_dark": "logo.png", + "alt_text": "pyOpenSci Python Package Guide. The pyOpenSci logo is blue and yellow following the Python logo", + }, + "header_links_before_dropdown": 4, + "use_edit_page_button": True, + "show_toc_level": 1, + #"navbar_align": "left", # [left, content, right] For testing that the navbar items align properly + "github_url": "https://github.com/pyopensci/python-package-guide", + "twitter_url": "https://twitter.com/pyopensci", + "footer_items": ["copyright"], +} + +html_theme_options["analytics"] = { + "google_analytics_id": "UA-141260825-1", +} + +html_context = { + "github_user": "pyopensci", + "github_repo": "python-package-guide", + "github_version": "main", } # Add analytics to furo theme @@ -90,7 +125,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'furo' +html_theme = 'pydata_sphinx_theme' html_static_path = ["_static"] html_css_files = ["pyos.css"] html_title = "pyOpenSci Package Guide" diff --git a/documentation/hosting-tools/intro.md b/documentation/hosting-tools/intro.md index 147b69009..ef23ccb92 100644 --- a/documentation/hosting-tools/intro.md +++ b/documentation/hosting-tools/intro.md @@ -12,15 +12,3 @@ when writing Sphinx documentation including mySt and rST. We also talk about ways to publish your documentation online and Sphinx tools that might help you optimize your documentation website. - -## Documentation build tools outline - -```{toctree} -:maxdepth: 2 - -Intro -Sphinx for Docs -myST vs Markdown vs rst -Publish Your Docs -Website Hosting and Optimization -``` diff --git a/documentation/hosting-tools/website-hosting-optimizing-your-docs.md b/documentation/hosting-tools/website-hosting-optimizing-your-docs.md index 7f675502e..41fa87a40 100644 --- a/documentation/hosting-tools/website-hosting-optimizing-your-docs.md +++ b/documentation/hosting-tools/website-hosting-optimizing-your-docs.md @@ -4,9 +4,10 @@ If you are interested in more people finding your package, you may want to add some core Sphinx extensions (and theme settings) that will help search engines such as Google find your documentation. -### Google Analytics +## Google Analytics ```{important} + Google analytics [is not compliant with the European General Data Protection Regulation (GDPR)](https://matomo.org/blog/2022/05/google-analytics-4-gdpr/). While there are many components to this regulation, one of the core elements is that you have to let users know on your site that you are collecting data and they have to consent. WHile it is possible to add infrastructure around Google Analytics to make it close to following GDPR regulations, the community is slowly shifting away from Google using open tools such as [Plausible](https://plausible.io/), [Cloudflare Web Analytics](https://www.cloudflare.com/web-analytics/) and [Matomo](https://matomo.org) for web analytics. pyOpenSci is currently looking into free options for open source diff --git a/documentation/index.md b/documentation/index.md index 12410f694..e2507376b 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -1,5 +1,49 @@ # Documentation for your Open Source Python Package +```{toctree} +:hidden: +:caption: Intro + +Documentation Overview +``` + +```{toctree} +:hidden: +:maxdepth: 2 +:caption: Write User Documentation + +Intro +Create Your Docs +Document Your Code (API) +Create Package Tutorials +``` + +```{toctree} +:hidden: +:caption: Core Repository Files +:maxdepth: 2 + +Intro +README file +Contributing File +Code of Conduct File +Development Guide +LICENSE files +``` + +```{toctree} +:maxdepth: 2 +:hidden: +:caption: Documentation & Hosting Tools + +Intro +Sphinx for Docs +myST vs Markdown vs rst +Publish Your Docs +Website Hosting and Optimization +``` + + ```{important} Please note that the tools discussed here are those that we see commonly used in the community. As tools evolve we @@ -125,10 +169,9 @@ View pyOpenSci peer review check list ```{figure} ../images/moving-pandas-python-package-github-main-repo.png --- -name: directive-fig +name: moving-pandas-github-repo-image width: 80% -alt: Image showing the files in the the MovingPandas GitHub repository. Files there include code of conduct.md, -Contributing.md, license.txt, readme.md. +alt: Image showing the files in the the MovingPandas GitHub repository. Files in the image include code of conduct.md contributing.md license.txt and readme.md. --- An example from the MovingPandas GitHub repository with all of the major files in it including CONTRIBUTING.md, README.md, CODE_OF_CONDUCT.md and a LICENSE.txt file. *(screen shot taken Nov 23 2022)* ``` diff --git a/documentation/repository-files/code-of-conduct-file.md b/documentation/repository-files/code-of-conduct-file.md index fe270a4aa..71c205ab1 100644 --- a/documentation/repository-files/code-of-conduct-file.md +++ b/documentation/repository-files/code-of-conduct-file.md @@ -1,7 +1,7 @@ # The CODE_OF_CONDUCT.md file In Your Python Open Source Package -```{tip} -## Example Code of Conduct files +```{admonition} Example Code of Conduct files +:class: tip * [SciPy Code of Conduct file - notice they included theirs in their documentation](https://docs.scipy.org/doc/scipy/dev/conduct/code_of_conduct.html) * [fatiando code of conduct file](https://github.com/fatiando/community/blob/main/CODE_OF_CONDUCT.md) diff --git a/documentation/repository-files/contributing-file.md b/documentation/repository-files/contributing-file.md index 2c1138c0d..6b7145246 100644 --- a/documentation/repository-files/contributing-file.md +++ b/documentation/repository-files/contributing-file.md @@ -2,8 +2,8 @@ ## What a CONTRIBUTING.md file should contain -```{tip} -## Example contributing files +```{admonition} Example contributing files +:class: tip * [pyGMT contributing file](https://github.com/GenericMappingTools/pygmt/blob/main/CONTRIBUTING.md) * [fatiando verde's contributing file](https://github.com/fatiando/verde/blob/main/CONTRIBUTING.md) diff --git a/documentation/repository-files/development-guide.md b/documentation/repository-files/development-guide.md index 26d4166eb..7bba5b56d 100644 --- a/documentation/repository-files/development-guide.md +++ b/documentation/repository-files/development-guide.md @@ -15,7 +15,7 @@ It's also helpful to specify the types of tests you request if a contributor sub If you have time to document it, it's also helpful to document your maintainer workflow and release processes. -### Why a development guide is important +## Why a development guide is important It's valuable to have a development guide, in the case that you wish to: diff --git a/documentation/repository-files/intro.md b/documentation/repository-files/intro.md index 3e82cf424..620ae40fd 100644 --- a/documentation/repository-files/intro.md +++ b/documentation/repository-files/intro.md @@ -4,17 +4,6 @@ In this section of the Python packaging guide, we review all of the files that you should have in your Python package repository. Your Python package should, at a minimum have the following files: -```{toctree} -:maxdepth: 2 - -Intro -README file -Contributing File -Code of Conduct File -Development Guide -LICENSE files -``` - The files mentions above (README, Code of Conduct, license file, etc) are used as a measure of package community health on many online platforms. Below, you can see an example how Github @@ -23,7 +12,7 @@ all GitHub repositories. ```{figure} /images/moving-pandas-python-package-github-community-standards.png --- -name: directive-fig +name: moving-pandas-github-community width: 80% alt: Image showing that the MovingPandas GitHub repository community health page with green checks next to each file including a description, README, code of conduct, contributing, license and issue templates. Note that Security policy has a yellow circle next to it as that is missing from the repo. --- @@ -36,7 +25,7 @@ in the Github repo as a measure of community health. ```{figure} /images/moving-pandas-python-package-snyk-health.png --- -name: directive-fig +name: moving-pandas-snyk width: 80% alt: Screenshot of the Snyk page for movingpandas. It shows that the repository has a README file, contributing file, code of conduct. It also shows that it has 30 contributors and no funding. The package health score is 78/100. --- diff --git a/documentation/repository-files/license-files.md b/documentation/repository-files/license-files.md index 7abdfb8d3..93bd98744 100644 --- a/documentation/repository-files/license-files.md +++ b/documentation/repository-files/license-files.md @@ -10,7 +10,7 @@ by the Open Software Initiative (OSI). OSI's website has a If you choose your license through GitHub, you can also automatically get a copy of the license file to add to your repository. -### Important: make sure that you closely follow the guidelines outlines by the License that you chose +## Important: make sure that you closely follow the guidelines outlines by the License that you chose Every license has different guidelines in terms of what code you can use in your package and also how others can (or can not) use the code in your package. diff --git a/documentation/repository-files/readme-file-best-practices.md b/documentation/repository-files/readme-file-best-practices.md index 88c960813..12afe8e46 100644 --- a/documentation/repository-files/readme-file-best-practices.md +++ b/documentation/repository-files/readme-file-best-practices.md @@ -16,12 +16,9 @@ health on sites such as: ```{figure} /images/pandera-python-package-readme-github.png --- -name: directive-fig +name: pandera-readme width: 80% -alt: README landing page screenshot for the Pandera package. It has the pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle: statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. -Below that are a series of badges including CI tests passing, docs passing, version of pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. -Finally below the badges the text reads: -Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust. +alt: README landing page screenshot for the Pandera package. It has the Pandera logo at the top - which has two arrows in a chevron pattern pointing downward within a circle. Subtitle is statistical data testing toolkit. A data validation library for scientists, engineering, and analytics seeking correctness. Below that are a series of badges including CI tests passing, docs passing, version of Pandera on pypi (0.13.4), MIT license and that it has been pyOpenSci peer reviewed. There are numerous badges below that. Finally below the badges the text says, Pandera provides a flexible and expressive API for performing data validation on dataframe-like objects to make data processing pipelines more readable and robust. --- Your GitHub repository landing page highlights the README.md file. Here you can see the README.md file for the pyOpenSci package [Pandera](https://github.com/unionai-oss/pandera). *(screen shot taken Nov 23 2022)* ``` @@ -138,8 +135,8 @@ Include descriptive links to: * The package's documentation page. * Short tutorials that demonstrate application of your package. -```{tip} -### Too Much Of A Good Thing +```{admonition} Too Much Of A Good Thing +:class: tip Try to avoid including several tutorials in the README.md file itself. This too will overwhelm the user with information. @@ -167,8 +164,8 @@ Finally be sure to include instructions on how to cite your package. Citation should include the DOI that you want used when citing your package, and any language that you'd like to see associated with the citation. -```{tip} -### README Resources +```{tip} README Resources +:class: tip Below are some resources on creating great README.md files that you might find helpful. diff --git a/documentation/write-user-documentation/create-package-tutorials.md b/documentation/write-user-documentation/create-package-tutorials.md index 108ec4d95..9df7e337b 100644 --- a/documentation/write-user-documentation/create-package-tutorials.md +++ b/documentation/write-user-documentation/create-package-tutorials.md @@ -8,7 +8,7 @@ to get started using your package. Ideally, those tutorials also can be run from start to finish providing a second set of checks (on top of your test suite) to your package's code base. -In the [documentation tools page](python-package-documentation-tools) we talk about two Sphinx extensions (`sphinx-gallery` and `nbsphinx`) +On this page, we review two Sphinx extensions (`sphinx-gallery` and `nbsphinx`) that allow you to create reproducible tutorials that are run when your Sphinx documentation builds. @@ -43,7 +43,7 @@ your documentation, the gallery extension: ```{figure} /images/sphinx-gallery-overview.png --- -name: directive-fig +name: sphinx-gallery width: 80% alt: Image showing the gallery output provided by sphinx-gallery where each tutorial is in a grid and the tutorial thumbnails are created from a graphic in the tutorial. --- @@ -55,7 +55,7 @@ Below you can see what a tutorial looks like created with sphinx-gallery. ```{figure} /images/sphinx-gallery-tutorial.png --- -name: directive-fig +name: spinx-gallery-tutorial width: 80% alt: Image showing ta single tutorial from Sphinx gallery. The tutorial shows a simple matplotlib created plot and associated code. --- diff --git a/documentation/write-user-documentation/document-your-code-api-docstrings.md b/documentation/write-user-documentation/document-your-code-api-docstrings.md index 522d19231..6b964357a 100644 --- a/documentation/write-user-documentation/document-your-code-api-docstrings.md +++ b/documentation/write-user-documentation/document-your-code-api-docstrings.md @@ -147,7 +147,7 @@ def extent_to_json(ext_obj): ```{figure} /images/sphinx-rendering-extent-to-json-earthpy.png --- -name: directive-fig +name: earthpy-json-example width: 80% --- Using the above NumPy format docstring in sphinx, the autodoc extension will @@ -193,15 +193,17 @@ def add_me(aNum, aNum2): ------- Prints the integer that you provide the function. + Examples + -------- + Below you can see how the `print_me` function will print a number that + you provide it. + + >>> add_me(1+3) + 4 + """ - return aNum + aNum2 -Examples --------- -Below you can see how the `print_me` function will print a number that -you provide it. + return aNum + aNum2 ->>> add_me(1+3) -4 ``` diff --git a/documentation/write-user-documentation/get-started.md b/documentation/write-user-documentation/get-started.md index aa0931939..baf72a6ac 100644 --- a/documentation/write-user-documentation/get-started.md +++ b/documentation/write-user-documentation/get-started.md @@ -57,7 +57,7 @@ page to the following elements: ```{figure} /images/geopandas-documentation-landing-page.png --- -name: directive-fig +name: geopandas-landing width: 80% alt: Image showing the landing page for GeoPandas documentation which has 4 sections including Getting started, Documentation, About GeoPandas, Community. --- diff --git a/documentation/write-user-documentation/intro.md b/documentation/write-user-documentation/intro.md index d84e81073..cab2d0142 100644 --- a/documentation/write-user-documentation/intro.md +++ b/documentation/write-user-documentation/intro.md @@ -13,14 +13,3 @@ easier such as: * autodoc to automagically populate documentation for your code's functions, classes, methods and attributes (API documentation) and * sphinx gallery for tutorials. - -## User-facing documentation sections - -```{toctree} -:maxdepth: 2 - -Intro -Create Your Docs -Document Your Code (API) -Create Package Tutorials -``` diff --git a/index.md b/index.md index be7e3894f..654054b44 100644 --- a/index.md +++ b/index.md @@ -1,5 +1,27 @@ # pyOpenSci Python Open Source Package Development Guide + +```{toctree} +:hidden: +:caption: Documentation + +Documentation +``` + +```{toctree} +:hidden: +:caption: Packaging + +Packaging +``` + +```{toctree} +:hidden: +:caption: CI and Testing + +CI & Tests +``` + @@ -40,7 +62,7 @@ Learn about our open peer review process -::::{grid} 1 1 1 2 +::::{grid} 1 1 2 2 :class-container: text-center :gutter: 3 @@ -58,17 +80,6 @@ documentation that are commonly used in the scientific Python community. ::: -:::{grid-item-card} -:link: code-style-structure/intro -:link-type: doc -:class-header: bg-light - -✨ Package Structure & Code ✨ -^^^ -Under Construction - Coming Spring 2023! -Learn more about standards for packaging structure and -builds in the scientific Python community. -::: :::{grid-item-card} :link: CONTRIBUTING @@ -109,36 +120,6 @@ This guide is now a work in progress. If you have ideas of things you'd like to see here, [we invite you to open an issue on GitHub that details any changes or additions that you'd like to see.](https://github.com/pyOpenSci/python-package-guide/issues). -```{toctree} -:hidden: -:caption: Documentation - -Documentation Overview -Write User Documentation -Core GitHub Repository Files -Documentation Tools & Hosting -``` - - -```{toctree} -:hidden: -:caption: Package structure & code style - -Intro - -``` - - - -```{toctree} -:hidden: -:caption: CI and Testing - -Intro -``` - - -