NumPy Documentation Team meetings

--- tags: NumPy --- # NumPy Documentation Team meetings - Time: 4pm UTC - Join via Zoom: https://zoom.us/j/96219574921?pwd=VTRNeGwwOUlrYVNYSENpVVBRRjlkZz09 - NumPy community events calendar: https://scientific-python.org/calendars/numpy.ics - Next meeting: June 6, 2022 ## Topics for June 6, 2022 ## Notes for May 23, 2022 **Present:** Melissa Mendonça, Rohit Goswami (@HaoZeke), Inessa Pawson (@inessapawson), Jake VanderVaate, Ricardo Prins (@ricardoprins), Ross Barnowski, Sebastian Berg, Matti Picus, Brigitta Sipőcz, Lev Maximov, Mukulika Pahari - [name=Rohit] Bumping to the top for some urgency (sorry): - [Mailing list discussion about PDF removal here](https://mail.python.org/archives/list/numpy-discussion@python.org/thread/CCTBM3GONFQWM3DUZRBBT3YYGKXGGPLT/) - Navigation for html is not ideal; this should be fixed irrespective of the PDF generation - There are issues of size of the docker image and other breakages coming from the LaTeX/PDF generation - Rohit makes a point that this is necessary for a possible group of people who are not voicing their needs on github/mailing list - Ross suggests refactoring the generation of the PDF docs to a scheduled CI job that has a designated maintainer (Rohit mentions he could take that up) - Lev mentions that .chm files are also a possibility, as well as Dash (MacOS), Velocity (Windows), Zeal (Linux, Windows), DevDocs (Chrome), Little Drops (Android). - Proposal: come up with a refactoring solution for the next docs meeting --> Rohit will have a demo - [name=Inessa] Translations on crowdin: https://support.crowdin.com/modifying-project-participants-roles/#project-roles - We should check if ownership transfer can be done with Shekhar (Inessa will contact Shekhar) - If not, we can check for an enterprise-level account with NumFOCUS - There was a [PR](https://github.com/numpy/numpy/pull/21522) to add a french readme, should we consider this or maybe consider this after on numpy.org is online? At this time, we are not planning on translating NumPy docs or anything else beyond numpy.org. - [name=bhavuk kalra] Tutorial on Finding and Editing Doc Strings(Rough draft) suggestions :- [Find and Edit Doc Strings](https://hackmd.io/Uv7TotDjRRKa3iuwf_PpCw?view) - [name=Melissa] https://hackmd.io/@melissawm/Sy1SGhvD9 - Melissa and Bhavuk to submit a (joint?) PR - [name=Melissa] https://github.com/numpy/numpy/issues/2067 - [name=Ross] NumPy tutorials CI issues - atari-py/gym is creating problems. The proposal is to freeze the Reinforcement learning notebook and remove those dependencies from requirements/CI. - [name=Brigitta] If the pytest doctesting goes forward with doctestplus, Brigitta would be interested in being involved in the team effort. [SDG proposal for pytest-doctestplus](https://hackmd.io/5uRx7MNhTqSLIFkPnFLY0g) ### For next meeting: - [name=bhavuk kalra] Should we close these PR's or Keep it around for further discussion - 1) [Revert PR for breathe](https://github.com/numpy/numpy/pull/21270) (Made just in case, If something didn't worked out). 2) [Update Gitpod FAQ](https://github.com/numpy/numpy/pull/21263) - [name=bhavuk kalra] Mathematical formulae rendering is slow, getting tracked in this issue - [MathJAX rendering is slow](https://github.com/numpy/numpy/issues/21419), suggestions on the test done? ## Notes for May 9, 2022 **Present**: Melissa Mendonça (@melissawm), Jake VanderVaate, Ross Barnowski, Sebastian Berg (@seberg), Mars Lee(@marsbarlee), Ricardo Prins (@ricardoprins), Mukulika Pahari (@Mukulikaa), Bhavuk Kalra, Matti Picus - [pydata-sphinx-theme community representatives](https://github.com/pydata/pydata-sphinx-theme/issues/645) - No action required at this point - PyCon 2022 Sprint - Hosted in-person by Inessa, 7-8 people attended - Not much for remote volunteers - Issue opened about difficulty building docs in Gitpod. Versioning problem with latest version of breathe - Should we issue a warning about using Gitpod? Ping a condaforge or breathe maintainer? - Melissa to ping a condaforge maintainer about this - Can probably be solved by switching breathe version from 4.33. to 4.31 - [name=Bhavuk Kalra] - "I can try with ubuntu. I also did the setup on remote desktop on azure and I had seen those warnings. I have been delaying it for a while now to finally test. I'll do it right now in the background" -> WARNING: doxygenfunction: Cannot find file... - Succesfully reproduced error but maybe specific to ubuntu - breathe or doxygen warning? - Sphinx still build docs, only thing not built at C examples - Gitpod still works, but these error messages can scare newcomers - Sphinx errors: sphinx designed as state machine, under the hood are various states, with rebuild different state from clean build. Good for cacheing, plug-ins into build process but difficult to trace back problem - Follow up discussion on issue created from previous meeting - [name=Jake] [Dark mode syntax highlighting isn't as color-blind friendly as the light mode](https://github.com/pydata/pydata-sphinx-theme/issues/649) - Current working solution is user changing theme colors individually - However, we want accessibility to be easier to access, bring upstream to theme - Someone could make PR of what a better dark mode 'native' theme could look like - We could push for this more, since [accessibilty has been identified as a priority for PyData Sphinx Theme](https://github.com/pydata/pydata-sphinx-theme/issues/61) - Ross is working on [updating numpy-tutorials](https://github.com/numpy/numpy-tutorials/pull/123) - Myst-NB supports alt-text - Renaming could apply only to NumPy tutorials - Looking at [NEP 44 Restructuing NumPy documentation](https://numpy.org/neps/nep-0044-restructuring-numpy-docs.html), nowhere is explicit method how to organize - Tutorials are currently organized by [Diátaxis framework](https://diataxis.fr/) - Lots of overlap in tutorials vs explanation - Could add tags, allowing things to be tagged with 2+ things (document both for beginners and explanation). Improve discoverability - Finding a custom directive that adds tags - Melissa, Lucy Liu working on sphinx-gallery tags, could bring back to NumPy tutorials - Possible UI: drop down bar of tags, click on one, opens an index page of that tag - Other projects could benefit from this, mathplotlib currently doing it by hand - Software testing - Need to remove outdated docs on testing - May move from runtests to the CLI SciPy has, maybe Meson - Can't run doctests with PyTest flags - Potential small development grant: moving from doctests to PyTest - Relatively well-defined, more about adoption - For someone interested in testing in documentation - [Apply for NUMFOCUS Round 2](https://numfocus.org/programs/small-development-grants) Call for Proposals Announcement: May 6, 2022 Proposal Submission Deadline: June 3, 2022 Committee Selection Deadline: June 17, 2022 Notification to Applicants Deadline: July 15, 2022 - Need someone to mention in this week's NumPy community meeting, Melissa won't be there but will crosspost on NumPy Slack - Opinions on the [card styling PR](https://github.com/numpy/numpy/pull/21456)? - [name=Ross] Make styling more consistent with other projects? For example with [pandas](https://pandas.pydata.org/pandas-docs/stable/) and [scipy](https://scipy.github.io/devdocs/index.html) - [name=Mars] Pamphile's PR makes resized images more proportional and centered in cards, so better than other projects. Differences from other projects are minor, still has strong visual link to other projects - Could move forward with merge for now - [name=Mukulika] Action item for [Need to remove easy_install usage from doc/Makefile](https://github.com/numpy/numpy/issues/18246)? - Possibility: Remove easy_install, replace with regular commands - Possibility: remove makedist, keep easy_install - No action needed now, Ralf and Chuck already discussing ## Notes for April 25, 2022 **Present**: Rohit Goswami, Inessa Pawson, Mars Lee, Jake VanderVaate, Ross Barnowski, Dilia Rueda, Matti Picus - [name=Mars Lee] Dark mode switcher - [Link to issue](https://github.com/numpy/numpy/issues/21390) - Recently implemented option (2 weeks ago) - Wait for the next PyData Sphinx Theme version to be officially released to implement this - Some feel like the black is too dark, Mars will open an issue in the PyData Sphinx Theme repo about customizing colors - [Example of multiple different dark mode switcher](https://doc.rust-lang.org/stable/book/) - [name=Jake] The light mode syntax highlighting is nicer for people with visual difficulties - In particular, the dark mode color choice of neon green + neon orange can be viewed as only orange by some people - [name=Rohit] We should deal with the font-locking (syntax highlighting separately) - [name=MattiP] Adding a link to [OpenTeams project page](https://www.openteams.com/app/marketplace/project-page-2/587809) for more support? worthwhile? - OpenTeams is very new intiative - OpenTeams has consultants and acts as a middle-man market. Companies ask OpenTeams for training and development of open-source tools - Link between NumPy, NumPy finances (NUMFocus, OpenColletive) and OpenTeams not clear yet - We should make clear that NumPy does not officially sanction the contractors/teachers - Not same as creating an issue - Spyder has some links - https://docs.spyder-ide.org/current/troubleshooting/call-for-help.html#openteams-support - https://docs.spyder-ide.org/current/installation.html#additional-help - Upside: There are already companies profitting from teaching and consulting NumPy. Might as well have a sanctioned partner - Downside: external consultants may move NumPy in non-community ways - Bring up to Steering Committee to think of statement and come back to issue - Need to have a clearer vision of what OpenTeams-NumPy relations would look like before adding an OpenTeams link - Short discussion on the calendar ics - Moving away from Google Calendar - Syncing problems - Need to subsribe to URL link to sync calendar - Download, import from file does not sync and therefore is not recommended - Currently only the HackMD link is present - Pros --> Even if people don't register through the web they can visit the page and get updates - Cons --> Kinda confusing sometimes, needs an additional layer of indirection - Possibility: implement calendar widget - [Jupyter uses in-browser, Google Calendar widget to show all their events](https://jupyter.org/community#calendar) - However, this brings us back to an implicit Google / Outlook / Other dependency - We should check that different - Make clearer instructions for syncing calendar across diffeernt services (Google Calendar, Outlook), [similar to this example](https://scientific-python.org/calendars/) - As of now, should subscribe by url +1 *Action item:* Inessa will communicate this info via all the existing channels. - TeX issues --> https://github.com/numpy/numpy/issues/19299 --- ## Notes for April 11, 2022 **Present**: Melissa Mendonça, Matt Danda, Inessa Pawson, Rajasekaran Karunanithi, Jake VanderVaate, Tapasweni Pathak, Mars Lee, Bhavuk Kalra, Mukulika Pahari, Harpreet Matharoo, Ross Barnowski, Peculiar Praise * [name=Inessa Pawson] NumPy newsletter - Project management via GitHub only: https://github.com/numpy/numpy-newsletter/projects/1 Please note the updated outline for the first issue of the newsletter. - Pamphile Roy is writing a blog post about numpy.random. (Aiming to include in the second issue.) - Inessa will add a link to the project in the repo README. - No set deadline for now, but work can move forward as writers/editors are available. – Inessa will look into what format is needed for Mailchimp. (Response: html) * [name=Inessa Pawson] April 7th NumPy Newcomers’ Hour Presenter: Mars Lee Topic: Making NumPy accessible with community workshops: how we can involve more people with disabilities in data science. A video recording is available on the NumPy YouTube channel: https://youtu.be/jI4pax8HX6c - [name=Melissa] [Social media guidelines](https://github.com/numpy/numpy.org/issues/437) - [name=Melissa] [DOC: * vs \cdot vs \cdotp vs \times? #21310](https://github.com/numpy/numpy/issues/21310) - Should only be about LaTeX math environments - We should limit the amount of LaTeX that goes into docstrings as they will be read on the terminal/repl/ipython console. - [name=Melissa] [DOC: define/use 'selection object' in basics.indexing.rst #20645](https://github.com/numpy/numpy/pull/20645) - Different terminology being used in different parts of the page - Do we mean "generic object" or "Python object"? The complication is that some cases result in basic indexing, while other result in advanced indexing (which can be very different in performance) - Need more input on what specific keywords mean. Maybe have a seperate section explaining it. - [name=bhavukkalra] [Adding Gitpod FAQ Debugging/Testing and building image locally](https://github.com/numpy/numpy/pull/21263). Working on it. Will create a new PR for building Gitpod image locally. Need suggestions on how the paths should look like. - Use a general path like `<path-to-your-repos>/numpy` - Feel free to use images for instructions; make sure alt-text is correctly added and that images are not too large - Google Season of Docs: questions and discussion - General note: Version switcher from the PyData Sphinx Theme has been enabled for SciPy: https://scipy.github.io/devdocs/index.html - PR https://github.com/scipy/scipy/pull/15380 ## Notes for March 28th, 2022 **Present**: Melissa Mendonça, Mukulika Pahari, Dilia, Inessa Pawson, Jake VanderVaate, Ross Barnowski, Matt Danda, Bhavuk Kalra, Somasree Majumder, Noa Tamir, Alex de Siqueira, Mars Lee, Rohit Goswami * NumPy newsletter * You can follow the development for the newsletter here: https://github.com/numpy/numpy-newsletter * Inessa will ping contributors who need to respond today, and possibly follow up with the outstanding items in the #newsletter channel on slack. * Interviews will be linked in the newsletter but will be hosted on the Scientific Python blog https://github.com/scientific-python/scientific-python.org * NumPy Newcomers’ Hour – April 7th, 2022 at 4 pm UTC Presenter: Mars Lee Topic: Making NumPy accessible with community workshops: how we can involve more people with disabilities in data science. * The NumPy community Google calendar will be deprecated on June 1st, 2022. Please subscribe to https://scientific-python.org/calendars/numpy.ics to keep track of all NumPy community events. * Version switcher has been merged to PyData Sphinx theme https://github.com/pydata/pydata-sphinx-theme/pull/611 * We should check to see how to add it to our docs (we need to check or restructure our old documentation first) * FWIW Pamphile is working on this for scipy: https://github.com/scipy/scipy/pull/15380 * [Thumbnails for numpy-tutorials landing page](https://github.com/numpy/numpy-tutorials/pull/123) don't support alt-text (yet). Should we wait for that? * Gitpod documentation build is broken right now - it seems like breathe is the issue. * https://github.com/numpy/numpy/issues/21252 * Suggestion: improve the gitpod documentation to include instructions on how to debug and test https://numpy.org/doc/stable/dev/development_gitpod.html#faq-s-and-troubleshooting * It is hard to test programmatically if the gitpod instance is working, but we should be checking it periodically to make sure new users don't face problems when using gitpod. * [name=rossbar] TODO: Open an issue about setting up CI/some sort of automated verification that the gitpod instance is working ## Notes for March 14th, 2022 **Present**: Melissa Mendonça, Noa Tamir, Alex de Siqueira, Jake VanderVaate, Inessa Pawson, Rohit Goswami, Mars Lee, Mukulika Pahari, Ross Barnowski, Bhavuk Kalra, Md Shahriyar Al Mustakim Mitul - Should we have a style guide like https://github.com/scipy/scipy/pull/13955? - Rohit suggests we could also get a guide for when to use each of the theme elements (like admonitions, warnings, sphinx panels etc) - This specific guide might not be directly applicable to NumPy. - Let's have our own guide since every project is different and we may not agree with any one external project - Could be phrased more as advice for beginners and documentation writers than guidelines to be enforced. But do we need another guide for beginners? - For newcomers, it could help them understand if information is needed vs optional - Potential GSOD project - PDF in docs (Noa has a suggestion) - Noa's suggestion: Recommend users to use 'Save/Print PDF' option in browser instead of NumPy team releasing PDFs - Letting the user customize the PDF output to be suited to their needs (accessibility) - Color - Fonts - Recently ran into the problem of not having the devdocs pdf ([name=Rohit] wanted to look up DLPack on my Kobo but I only had 1.22 which didn't include it -_-) - We could enable plausible tracking for that link - Some members are against switching away from LaTeX because of size, hyperlinks and the fact that we don't need syntax highlighting for most pdf outputs - We should split the PDF into chapters and distribute it as a zip similar to the way Python documentation is provided - [name=Rohit] is willing to help with TeX clean up to save the PDFs - We should make documentation of making the PDF if we go forward with this - Related issue: https://github.com/numpy/numpy/issues/19299 - Mukulika’s presentation for the latest NumPy Newcomers Hour has been posted: https://youtu.be/5bfFI2WuuMA - GSoD (March 25th) - Detailing how people actually navigate through the documentation - People/Personas, Journey Maps - A proposal for a tutorial: https://mail.python.org/archives/list/numpy-discussion@python.org/message/DTIS7BNGOJU7YZZNAAYUEYIRXTEIKTJW/ - To get feedback and concrete ideas, feel free to open an issue on https://github.com/numpy/numpy-tutorials - Make sure we explain the motivations behind building these algorithms using only NumPy (are there use cases for this, or is it purely pedagogical?) - Concrete suggestions (more) --> no external libraries - NumPy newsletter: - Contributors are needed: https://docs.google.com/document/d/1RDL328nJiwVZVFR-A2jii1p_kcgvuSOn9Dihb75ecB4/edit?usp=sharing - Extended discussion: what extent, option and format does the Newsletter or other teams integrate into the wider NumPy community? - Let people decide what extent they want to join - Slack as a central place for all teams - But Slack may be overwhelming for someone interested in only 1 team - Creating multiple points of entry for contributors - While more options/point of entry could be overwhelming, there is Inessa as NumPy Experience Lead to follow and help along new contributors - Can discuss further in Community Meeting - General comment: we could have a form at the homepage instead of asking people to send an email to join the slack - Lower barrier of entry - Could use LinkTree # Notes for February 28th, 2022 **Present:** Inessa Pawson, Ganesh Kathiresan, Elizabeth Brown, Matt Danda, Ross Barnowski, Mukulika Pahari, Jake VanderVaate, Vasiliy, Mars Lee, Alex de Siqueira - [Proposal to remove the PDF version of the **SciPy** docs](https://mail.python.org/archives/list/scipy-dev@python.org/thread/E2NNGLDZDOKD65Z2FW3TINZ2A2GQGHP5/) - Process: Run Sphinx which convert rst (input format) to docutils (abstract syntax tree) to LaTex (typesetting technical document) - LaTex makes PDFs. However, PDF formatting not good- linking not good, take forever to build. - SciPy already considering to stop running LaTeX. Save time. Already provide zipped HTML docs, which are better formatted than PDFs - Should we think about doing the same? - Reasons to not do it: Some people use PDF documention, such as with spotty internet may want PDF. But we should push to use zipped HTML anyway - How many people use the pdf docs? How do we get feedback from the community on this issue? * ask on the mailing list, but be aware that the response will be developer-biased * ask on the Gitter and StackOverflow - Ideas: * Remove from CI, but keep available during release - Puts more on Chuck's shoulders/need some extra helpers for the release process * Move it to a scheduled job * Provide instructions on how to build docs from source (pdf/html) - Difficult for non-developer users, of which there are many - [DOC: define/use 'selection object' in basics.indexing.rst #20645](https://github.com/numpy/numpy/pull/20645) * Will have some extra eyes on it :tada: * Seems relatively subjective at first glance, probably needs a closer look to really suss out all of the potential technicalities - [SciPy extensions for code style and docstring guidelines](https://github.com/scipy/scipy/pull/13955) - Pointing to a policy vs automatic enforcer vs linter - Ross' preference: Remove unneccsary policies, would prefer enforcer. For example, current docs point to Chicago Manual of Style- but realistically nobody refers or enforces it. - Present most important information first: NumPy style guide should be priortized over Chicago Manual of Style - https://developers.google.com/season-of-docs/docs/timeline - The idea is to have a joint project with SciPy to update the [SciPy Lectures](https://scipy-lectures.org/) - NumPy newsletter After considering everyone’s input, Inessa proposed to collaborate on the content of the NumPy newsletter directly on GitHub. If it proves to be inefficient, we will consider other options that we discussed at the previous meeting (e.g., HackMD, HedgeDoc, Etherpad, etc.). --- ### 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.