NumPy Documentation Team meetings

--- tags: NumPy --- # NumPy Documentation Team meetings - Time: 4pm UTC - Join via Zoom at: [link](https://zoom.us/j/96219574921?pwd=VTRNeGwwOUlrYVNYSENpVVBRRjlkZz09 ) - Next meeting: 25 October 2021 # Notes from 25 October 2021 **Present:** Melissa Mendonça, Mukulika Pahari, Ross Barnowski, Ryan Cooper, Mars Lee, Holam Gadol - GSoD updates: final stretch! - *November 16 - 30, 2021 at 18:00 UTC Organization administrators submit their case study and final project evaluation* - Let's work on the case study here: https://hackmd.io/@melissawm/HkuZuIN8K - [Indexing How-to](https://github.com/numpy/numpy/pull/20093) - Under review - [Copies and Views](https://github.com/numpy/numpy/pull/19791) - Under review - Add a note for [this issue](https://github.com/numpy/numpy/issues/20100) - [Tutorial:Analysis of air pollution levels before and after lockdowns](https://github.com/numpy/numpy-tutorials/issues/110) - In discussion, not a PR yet - [Explanation on Interoperability](https://github.com/numpy/numpy/pull/20185) - NumPy tutorials - Adding a translation policy blurb to the README of numpy-tutorials [name=Melissa] - [Tutorial: NumPy natural language processing from scratch with a focus on ethics](https://github.com/numpy/numpy-tutorials/pull/105) - Under review, CI is passing now - [atari-py dependency](https://github.com/numpy/numpy-tutorials/issues/87) [name=Mukulika] - Low priority, should be easy to fix - [Refactor development documentation?](https://numpy.org/devdocs/dev/index.html) - Complex and scattered. A review would be nice. - Add CircleCI preview instructions to developer docs - [A nice idea from matplotlib: rename CircleCI job so it's easy to spot rendered docs pages](https://github.com/matplotlib/matplotlib/pull/21423) - [NumPy Docs front page redesign](https://github.com/numpy/numpy/pull/19756) update [name=Mars] - Unable to reach design goals due to default sphinx-panel styling - Make an issue with sphinx-panels to make this an option ![](https://i.imgur.com/dqfJwaN.png) - Change image location from doc/neps/_static_ to doc/source/_static - Rebased so now CI passes! - [CircleCI preview](https://22829-908607-gh.circle-artifacts.com/0/doc/build/html/index.html) still not showing SVGs - Chrome issue so switch browsers, such as to Firefox - [moving from `refguide_check.py` to pytest](https://github.com/numpy/numpy/issues/15846#issuecomment-948051075) - Refactor PR template to include checklists. - Add instruction for title in issue forms. ## New document ideas: - Idea: [How to partition a domain using NumPy](https://github.com/numpy/numpy/issues/19670#issuecomment-916884703), with differences between arange, linspace, ogrid and mgrid. - [Typed NumPY API usage issue](https://github.com/numpy/numpy/issues/19875) - [How to find your way in the code?](https://github.com/numpy/numpy/issues/15567) - Tracking F2PY usage per standard, kinda like --> https://docs.lfortran.org/progress/ [name=Rohit] # Notes from 11 October 2021 **Present:** Melissa Mendonça, Ross Barnowski, Mukulika Pahari, Mars Lee, Rohit Goswami - GSoD updates - *November 16 - 30, 2021 at 18:00 UTC Organization administrators submit their case study and final project evaluation* - [Case study template](https://developers.google.com/season-of-docs/docs/case-study-template), [Sample case study](https://developers.google.com/season-of-docs/docs/case-study-example) - [Indexing How-to](https://github.com/numpy/numpy/pull/20093) - Up for review! :tada: - [Copies and Views](https://github.com/numpy/numpy/pull/19791) - Almost there! - Can we list which operations/functions create copies and which create views? using `may_share_memory`? Let's do this in another issue - Mukulika is deciding on a tutorial to write - Adding a translation policy blurb to the README of numpy-tutorials [name=Melissa] - [NumPy Docs front page redesign](https://github.com/numpy/numpy/pull/19756) update [name=Mars] - Close to CI preview - Image file location? - doc/source/user/images vs doc/neps/_static/ vs doc/source/_static - correct filepath: doc/neps/_static/ because of html_static_path = ['_static'] in conf.py - Ethics tutorial: what to do about data ## New document ideas: - WIP: doc on interoperability with other array libraries. [name=Melissa] - Idea: [How to partition a domain using NumPy](https://github.com/numpy/numpy/issues/19670#issuecomment-916884703), with differences between arange, linspace, ogrid and mgrid. - [Typed NumPY API usage issue](https://github.com/numpy/numpy/issues/19875) - [How to find your way in the code?](https://github.com/numpy/numpy/issues/15567) - Tracking F2PY usage per standard, kinda like --> https://docs.lfortran.org/progress/ [name=Rohit] --- # Notes from 27 September 2021 **Present:** Ross Barnowski, Mukulika Pahari, Mars Lee, Ganesh Kathiresan, Inessa Pawson, Ryan Cooper - GSoD updates - [Copies v. Views](https://github.com/numpy/numpy/pull/19791) * Recently updated - needs review - Indexing how-to: incoming - Experimenting with Doxygen * It turns out there's an existing Doxyfile in NumPy already - not sure if it's used or not: https://github.com/numpy/numpy/blob/main/doc/cdoc/Doxyfile - Action Item: Mukulika will raise an issue about this - [Typed NumPY API usage issue](https://github.com/numpy/numpy/issues/19875) * Let's bring this up at the next community meeting to get Bas' feedback - [How to find your way in the code?](https://github.com/numpy/numpy/issues/15567) - [Guidelines on how to find the correct file to edit (see issue comment here)](https://github.com/numpy/numpy/issues/19952#issuecomment-927907185) * Are there docs about the C-templating engine? - If not, there should be! Basics - usage, syntax, etc. * GitHub Next: https://next.github.com/projects/repo-visualization - Is it worth documenting what functionality is defined in C/Cython/Python? * The main benefit would probably be for new contributors who were more comfortable with Python than lower-level languages in steering them towards source code that they're more comfortable with. - [Source links for C code issue](https://github.com/numpy/numpy/issues/19520) - Can we have a standard way to reply to people who want to edit docstrings? (this might make our lives easier and help first-time contributors) * Bots/CI services to help with pointing to contributing docs? * e.g. https://github.com/moja-global/FLINT-UI/issues/75#issuecomment-919055489 * Simplify contributing docs to make them for readable? * Have a "how-to" that illustrates how to contribute e.g. a docs PR * Incorporate pictoral/visual info on the procedure * Incorporate link to newcomer's hour to contributing guides! * Action Item: Let's open an issue (in numpy-tutorials to start) about contribution walkthroughs. * [Related issue about first time contributors](https://github.com/numpy/numpy/issues/19778) - [Translation of NumPy-Tutorials](https://github.com/numpy/numpy-tutorials/issues/109): should we include an official policy in the README? * Adding a translation policy blurb to the README - [Drishti's NLP-Ethics Tutorial](https://github.com/numpy/numpy-tutorials/pull/105) - We are considering using [Pooch](https://pypi.org/project/pooch/). Drishti is investigating. If this is not appropriate, we might want to mark this document to be skipped by CI and let people run that locally only (with instructions about how to obtain the files). - Some ideas: * GitHub LFS? * Cloud data services? a NumPy/SciPy/Scientific Python discount? Maybe we could ping NumFOCUS about setting up an ecosystem-wide solution here. # Notes from 13 September 2021 **Present:** Rohit Goswami, Mars Lee, Melissa, Mukulika Pahari, Ryan Cooper, Ross Barnowski - GSoD updates - [Copies v. Views (WIP)](https://github.com/numpy/numpy/pull/19791) - [Moved NumPy Internals to Under-the-hood documentation for developers](https://github.com/numpy/numpy/pull/19865) - [Added missing C-API functions](https://github.com/numpy/numpy/pull/19844) Trying it out with Doxygen-Breathe. - [Drishti's NLP-Ethics Tutorial](https://github.com/numpy/numpy-tutorials/pull/105) - CI/caching of data. Intake catalog? - Code and text review - [refguide_check fix](https://github.com/numpy/numpy/pull/17222): re-enable checking for currently disabled documents - https://pypi.org/project/pytest-doctestplus/ - PyCon India Sprint (September 20th) - [Newcomer Friendly Issues](https://hackmd.io/9pfJGVlVSVKKOQgCFsjqLQ) - Here's a possible low-code way people can contribute- using Github Suggestions feature to make changes in the documentation - Recent example: [Adding alt-text to NumPy documentation](https://github.com/melissawm/numpy/pull/27) - For this sprint, a new PR could be made that focuses on other parts of the documentation ## Proposed topic for 9/13 Applying automatic code-formatting to the tutorials - See [numpy/numpy-tutorials#95](https://github.com/numpy/numpy-tutorials/pull/95) for details # Notes from 30 August 2021 **Present:** Melissa Mendonça, Angellica, Mukulika Pahari, Matti Picus, Mars Lee, Yashasvi Misra, Ross Barnowski, Ryan Cooper, Rohit Goswami ## Topics - GSoD updates - [Moving NumPy Internals to under-the-hood docs](https://github.com/numpy/numpy/issues/19689) - (from last meeting) Writing a Copies vs. Views document - How to check if NumPy will do a copy or not? - Should we use the `shares_memory` or `may_share_memory` flags? - Mukulika will submit a PR shortly - [Tighten contribution guidelines](https://github.com/numpy/numpy/issues/19778) - (Related) [GitHub Issue Forms](https://github.com/scipy/scipy/pull/14493)? - Let's try this with the existing templates, making sure that we don't impose too much structure on contributors - (from last meeting) [How to find your way in the code?](https://github.com/numpy/numpy/issues/15567) - Mukulika and Yashasvi are thinking about this - [Doxygen/Breathe C/C++ Documentation support PR](https://github.com/numpy/numpy/pull/18884) - This adds one extra step to docs building (installing doxygen) - Is it possible to ignore that if we only want the python docs? -> yes; we'll miss a few rst files but this should not stop sphinx from finishing building the docs - Rohit suggest looking into [doxyrest](https://github.com/vovkos/doxyrest) as it is faster than Breathe; however it's not clear this is a bottleneck for us right now. [Rohit's notes on his SymEngine GSoD project](https://rgoswami.me/posts/symengine-gsod20/) - We should add doxygen to environment.yml, pin the version and add a note to the contributing docs - Rohit also questioned the usability of documentation (generated with `doxyrest` or `breathe`) which do not link to code and obscure the implementations - The standard doxygen HTML documentation itself includes code and is richer in terms of informational content\ - Is the change of theme that big of an issue? - Docs front-page re-design: small update - [Draft PR](https://github.com/numpy/numpy/pull/19756) made - Removed references to html templates - f2py docs - Rohit asks what is the right way to add documentation to fortranobject.c/fortranobject.h and document the fortran code - Drishti's work on an ethics-focused tutorial for NumPy Tutorials: caching, CI and other issues (Drishti is a Quansight intern) - Khushi is also a Quansight intern, and is submitting a benchmarking page to numpy.org # Notes from 16 August 2021 **Present:** Melissa Mendonça, Yashasvi Misra, Ryan Cooper, Mukulika Pahari, Mars Lee, Anne Bonner ## Topics - GSoD updates - [Ufuncs doc](https://github.com/numpy/numpy/pull/19516) merged - Move [NumPy internals](https://numpy.org/devdocs/reference/internals.html) to Under the hood docs ([issue](https://github.com/numpy/numpy/issues/19689))? - This would make the Fundamentals aimed towards users and the "Under the hood" section aimed towards developers, having more low-level discussions about memory management etc - [Indexing how-to discussion issue](https://github.com/numpy/numpy/issues/19586) - [Indexing PR](https://github.com/numpy/numpy/pull/19407) - Writing a Copies vs. Views document - How to check if NumPy will do a copy or not? - Should we use the `shares_memory` or `may_share_memory` flags? - [How to find your way in the code?](https://github.com/numpy/numpy/issues/15567) - Mukulika and Yashasvi are thinking about this - [Alt text sprint from last week](https://github.com/numpy/numpy-tutorials/issues/96) - [NumPy Docs](https://github.com/melissawm/numpy/pull/27) - On Melissa's fork for now - [NumPy Tutorials](https://github.com/numpy/numpy-tutorials) PRs: #97, #99, #100, #101 - [SPEC Discussion](https://discuss.scientific-python.org/t/discussion-accessible-open-source-projects/63) # Notes from 2 August 2021 **Present:** Melissa Mendonça, Mukulika Pahari, Isabela Presedo-Floyd, Mars Lee, Ross Barnowski ## Topics - We have three pages about documentation building, can we merge them? - https://numpy.org/devdocs/dev/howto-docs.html (only reachable from within the developer documentation) - https://numpy.org/devdocs/docs/index.html (reachable from the main toctree in the sidebar) - https://numpy.org/devdocs/doc_conventions.html (top level) - Mukulika will work on opening an issue - GSoD updates - [Ufunc doc](https://github.com/numpy/numpy/pull/19516) - [Indexing how-to discussion issue](https://github.com/numpy/numpy/issues/19586) - Mukulika will send a note to the mailing list - [Indexing doc](https://github.com/numpy/numpy/pull/19407) - What should we do about the stub doc in reference guide now that everything has been shifted to the fundamentals doc? - Working on the internal array representation doc - Docs Front-page re-design - [Github issue link](https://github.com/numpy/numpy/issues/18419) - Implement Sphinx panels following Pandas' example - [Prototype from a few months ago](https://github.com/numpy/numpy/issues/18419#issuecomment-840078589) - Discussion continues in similar issues, such as in [DOC: Discussion - How to organize tutorials](https://github.com/numpy/numpy/issues/19191) - Mars to open an issue to compile everything in one place and ping Melissa, Ross - At the last NumPy newcomers meeting there was an alt text sprint for the docs. We used a checklist from [this document](https://hackmd.io/y_GiwWGVQFaPyOT7ti6SaA?view) which also has a proposed alt text style guide. As this gets polished, would you like to have this as a part of the NumPy docs in some way? - This is the PR we worked on: https://github.com/melissawm/numpy/pull/27 - This could go into the SPEC accessibility discussion - Isabela and Mars will work on that - What to do about [Under-the-hood docs](https://numpy.org/devdocs/dev/underthehood.html)? - maybe we should just remove it? There's no content under it - Internal array representation would fit here? - Some scipy lecture notes documents would also fit here # Notes from 19 July 2021 **Present:** Melissa Mendonça, Matti Picus, Mukulika Pahari, Mars Lee, Ross Barnowski, Ryan Cooper, Yashasvi Misra, Isabela Presedo-Floyd ## Topics - GSoD updates - Broadcasting doc merged :tada: - [Indexing doc](https://github.com/numpy/numpy/pull/19407) under review - Ufuncs documentation - Relevant issues [#19494](https://github.com/numpy/numpy/issues/19494) and [#16924](https://github.com/numpy/numpy/issues/16924) - [Draft PR](https://github.com/numpy/numpy/pull/19516) - Next: internal representation of arrays - Mukulika asks about the `[source]` button on the reference docs; some pages are missing this link. Apparently, these are the functions/objects with docstrings generated by `_add_newdocs.py` Mukulika will add an issue but this is low priority. - [Organization of reference docs](https://github.com/numpy/numpy/issues/19420) - We are open to a PR to add this page as long as it's generated automatically and easy to maintain. Maybe autosummary/automodule or some auto- tool can generate this page. - [New NumPy tutorials contribution?](https://github.com/numpy/numpy-tutorials/issues/92) - [Sphinx warnings issue](https://github.com/numpy/numpy/issues/13114#issuecomment-881227962) - [Sphinx bug: Logo and favicon not showing in devdocs](https://github.com/numpy/numpy/issues/19509) - Seems to be fixed in [new sphinx release](https://github.com/sphinx-doc/sphinx/issues/9438) (thanks Mukulika for chasing that down). - We probably want to do the same as SciPy https://github.com/scipy/scipy/pull/14417 - Check if dependabot missed this (apparently not, it updated to 4.1.0 7 days ago so the weekly update will probably trigger today)? - Are there any relevant documentation guidelines besides [A guide to NumPy documentation](https://numpy.org/devdocs/docs/howto_document.html), and the [Google developer documentation style guide](https://developers.google.com/style)? Does the [NumPy tutorials style guide](https://github.com/numpy/numpy-tutorials/blob/main/content/tutorial-style-guide.md) count? - Maybe [The Chicago Manual of Style](https://www.chicagomanualofstyle.org/home.html)? - They aren't referenced in the main docs, but there's also [Microsoft](https://docs.microsoft.com/en-us/style-guide/welcome/) and [Mailchimp's](https://styleguide.mailchimp.com/) style guides. # Notes from 5 July 2021 **Present:** Melissa Mendonça, Isabela Presedo-Floyd, Mars Lee, Matti Picus, Mukulika Pahari ## Topics - Google Season of Docs update - [Indexing PR](https://github.com/numpy/numpy/pull/19407) - [Broadcasting PR](https://github.com/numpy/numpy/pull/19369) - Next: [Create a documentation page for ufunc](https://github.com/numpy/numpy/issues/16924) - Adding documentation on how to run doctests - At some point we should migrate to doctestplus ([issue](https://github.com/numpy/numpy/issues/15845)) but Mukulika doesn't need to focus on that right now. - [DOC: 'Governance' in Sphinx pages: delete/move/keep? #17496](https://github.com/numpy/numpy/issues/17496) - Move this page to numpy.org (keep a link) - Interoperability with NumPy (Dask, Cupy, protocols) (Melissa) - What would you like to see? - [PR for accessibility testing in the PyData Sphinx theme](https://github.com/pydata/pydata-sphinx-theme/pull/294) is still open. You can comment if you feel inspired to push for this since it will influence NumPy too! - [Mukulika mentions she might get to work on this issue](https://github.com/numpy/numpy/issues/15793) on the internal representation of NumPy arrays. - Mukulika also mentions that we don't know if the survey participants are looking at stable or devdocs. Melissa will talk to Inessa to make sure we pick the right version of the docs to analyze. --- # Notes from 21 June 2021 **Present:** Melissa Mendonça, Mukulika, Ross Barnowski, Ryan Cooper, Mars Lee, Matti Picus - GSoD updates - [Broadcasting](https://github.com/numpy/numpy/issues/19136) - [Indexing](https://github.com/Mukulikaa/numpy/issues/3) - Matti suggests cleaning up the [random number API docs/user guide](https://numpy.org/devdocs/reference/random/index.html), [Random reference docs](https://numpy.org/devdocs/reference/random/generator.html) - what happens when you search google/duckduckgo for numpy devdocs? I sometimes get https://devdocs.io/numpy~1.19/ - This looks to be a [freeCodeCamp project](https://github.com/freeCodeCamp/devdocs) - We should add a link to the "canonical" docs at the Welcome message in our devdocs. - Another idea is to add a top banner in our theme that only renders when not in the numpy.org site. - In [the devdocs Github repo]([https://](https://github.com/freeCodeCamp/devdocs)), it looks like there are PRs for small documentation fixes ([such as for Nim](https://github.com/freeCodeCamp/devdocs)) if anyone wants to make changes on the devdocs side - There are similar Github issues such as for [C++](https://github.com/freeCodeCamp/devdocs/issues/1560), but not sure if the C++ maintainer or devdoc maintainer makes this change - Numpy Tutorials - [Github issue](https://github.com/numpy/numpy/issues/19191) - Reorganize current sphinx tutorials into numpy-tutorials or NumPy Fundamentals seems to be the best solution - Investigate how to use tags to organize the contents (Melissa will check for sphinx extensions to do that) - Docs building - Ross brings up a problem with the docs build because of the pinned sphinx version in our environment.yml/doc_requirements.txt files. A quick fix would be to un-pin sphinx and [disable the collapsible navbar](https://github.com/pydata/pydata-sphinx-theme/issues/364) to reduce the build times. # Notes from 7 June 2021 **Present:** Melissa Mendonça, Matti Picus, Ross Barnowski, Mars Lee, Isabela Presedo-Floyd, Mukulika, Juan Luis Cano, Ryan Cooper - Crosslinking Gitpod guide in other pages - [Github issue](https://github.com/numpy/numpy/pull/19185) - Check for 80 character line breaks instead of line wrap in gitpod (install rewrap extension in gitpod?) - GSoD Update - Mukulika has had some PRs merged and has others waiting - [Documentation audit spreadsheet](https://docs.google.com/spreadsheets/d/1_YctV5JnWCfR__NTSoXLhX_8W1c57b06XLDNp77-X90/edit#gid=0) - Melissa and Ross will track Mukulika's branch for updates - Sharing a helpful blog: [Accessibility Concerns for Content Staff](https://blog.tenon.io/accessibility-concerns-for-content-staff/) --- ### Useful links - Getting started with building documentation: https://www.numpy.org/devdocs/docs/index.html - How to contribute to the NumPy documentation: https://numpy.org/devdocs/dev/howto-docs.html - Meeting archives: https://github.com/numpy/archive ## Notes Github Repos: github.com/numpy/numpy - main numpy repo code and docs github.com/numpy/numpy-tutorials - narrative documentation repository github.com/numpy/numpy.org - "front page" of numpy, will be expanded github.com/scipy/scipy github.com/scipy/scipy.org - "front page" of scipy github.com/scipy/docs.scipy.org - one page TOC for documentation https://github.com/scipy/scipy-sphinx-theme - theming for sphinx use - CZI grant for 2020 [goals & deliverables](https://figshare.com/articles/Proposal_NumPy_OpenBLAS_for_Chan_Zuckerberg_Initiative_EOSS_2019_round_1/10302167) - CZI grant for 2021 [goals & deliverables](https://figshare.com/articles/online_resource/Improving_usability_and_sustainability_for_NumPy_and_OpenBLAS/13269167)

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.