[ad_1]
The Chan Zuckerberg Initiative (CZI) has funded SymPy as a part of Cycle 4 of its
Important Open Supply Software program for Science (EOSS)
grant program. As a part of this work, Aaron Meurer labored on enhancing the SymPy
documentation, with a concentrate on writing new narrative documentation guides.
SymPy is a mature mission, and has over 1000 features and lessons. Most of
these features and lessons have API reference documentation within the type of
docstrings, however the SymPy documentation has traditionally been missing in
long-form narrative documentation to complement these reference docs.
On this publish, I’ll go over among the key documentation enhancements that
have been revamped the course of the 2-year grant interval. Be aware that the
documentation enhancements have been just one a part of the CZI grant to enhance
SymPy. Different SymPy builders have been funded to enhance the efficiency of
SymPy, and to enhance
its code era
capabilities.
To start out the mission, from November 29, 2021 to January 5, 2022 we ran a brief
survey on the SymPy group, to get a really feel for SymPy’s documentation wants.
We had three takeaways.
One – the principle SymPy documentation website (https://docs.sympy.org) is overwhelmingly
the preferred useful resource that folks use to get assist with SymPy. That is
true throughout all ranges of expertise, in comparison with different sources just like the
SymPy web site, StackOverflow, and group websites (notice: this survey was
given in 2021, earlier than the recognition of LLM instruments like ChatGPT, so this was
not included as an choice for respondents).
Consequently, we determined that it could be most impactful to spend efforts on
enhancing the documentation website over these different sources.
Two – survey respondents recognized many deficiencies within the SymPy docs which
made it clear that sure enhancements wanted to be made to the general
structure and group of SymPy’s documentation website. Particularly, we
recognized 4 main enhancements that may very well be made:
- Higher top-level group.
- A greater Sphinx theme that gives higher sidebar navigation.
- The docs have many giant pages which might profit from being break up into smaller pages.
- There have been a number of points with the SymPy Reside extension. This was a
Sphinx extension that allowed customers to execute the instance code blocks in
the SymPy documentation immediately of their browser.
Of those, all besides the third, splitting giant pages, have been completed as a part of the
CZI grant work. Splitting giant pages hasn’t been completed but attributable to technical
difficulties with the Sphinx autodoc extension, in addition to attributable to the truth that
the big pages are actually a lot simpler to navigate with the brand new Sphinx theme.
The SymPy Reside extension within the documentation was eliminated, because it was
thought-about an excessive amount of of a upkeep burden for the SymPy group to
preserve. There’s a new SymPy Reside shell that
runs on JupyterLite — that
is, it runs fully within the browser utilizing
Pyodide. We’re hopeful that the
JupyterLite group can provide you with an equal SymPy Reside-like
extension that in order that we are able to re-enable comparable performance within the SymPy
documentation.
Three – we have been been capable of determine some major areas to prioritize for
writing new documentation guides.
Click on in case you want to learn the full survey outcomes.
Previous to this mission, the SymPy documentation used the “traditional” Sphinx
theme. This is identical theme that’s utilized by the official Python
documentation, however it’s outdated in some ways. It
lacks interactive navigation. As might be seen from the screenshot beneath, the
structure of the web page within the context of the remainder of the documentation is barely
proven by a small breadcrumb on the prime of the web page. The general structure of the
subheadings on the web page was given by a desk of contents on the left aspect of
the web page, however this was onerous to navigate. SymPy’s inexperienced shade scheme,
whereas giving the docs a particular taste, had poor distinction in some
locations such because the left sidebar, making it troublesome or inconceivable to learn
for individuals with low imaginative and prescient. It can’t be seen from these screenshots, however the
traditional Sphinx theme doesn’t work properly on cell (the parts
don’t scale to smaller display sizes in any respect), and it doesn’t have native help
for darkish modes.
So as to choose a alternative theme, we ran a second survey
from February 5-19, 2022. The outcomes of that survey are summarized. The
candidate themes have been Learn the Docs, PyData Sphinx Theme, E book, and Furo
Based mostly on the outcomes of the survey, we determined to make use of the Furo theme. The Furo
theme was ranked the best by survey respondents. Particularly, they appreciated
the improved sidebar navigation, the darkish mode, and cell help.
Moreover, Furo has good accessibility and the CSS is straightforward to customise.
The result’s a documentation website that has navigable sidebars. We spent
appreciable time retheming the default Furo colours to match the normal
SymPy inexperienced theme. This included including a darkish mode set of colours (this may be
accessed by clicking the circle icon on the prime of a docs web page, or by setting
your machine to make use of darkish mode). We took care to verify all shade
combos used all through the documentation have been at the very least WCAG degree
AA shade distinction in order that textual content might be perceived by a large viewers
of readers, together with many with low imaginative and prescient. This included
modifying the Pygments syntax highlighting
types
to have higher shade distinction.
A associated mission was reorganizing the top-level group of the
documentation. The SymPy documentation predominant web page used to only encompass an extended
record of each web page within the documentation. The brand new Furo theme makes this record
pointless, however it additionally gave us a chance to discover how these pages might
be explored in a extra logical approach.
We determined to undertake the Diátaxis framework for
documentation group. Diátaxis splits documentation pages into one in every of 4
classes, relying on whether or not the reader is fascinated by sensible or
theoretical information, and on whether or not they have examine or work oriented objectives. As
might be seen from the present documentation predominant web page, the docs are actually organized
into 4 classes: tutorials, how-to guides, explanations, and API reference.
We moreover added “set up” and “contributing” as separate top-level
classes. Set up is essential sufficient to warrant calling out
documentation for it individually. Contribution documentation is separate as a result of
it serves a separate viewers, individuals who need to contribute to SymPy, relatively
than people who find themselves fascinated by utilizing it.
Along with this, we reorganized the handfuls of API reference
pages into eight
sub-categories: Fundamentals, Code Technology, Logic, Matrices, Quantity Principle,
Physics, Utilities, and Subjects.
Probably the most essential issues an open supply mission can do to draw new
contributors is to have good contributor documentation. SymPy has traditionally
had a wealth of contributor documentation, however a lot of it was outdated.
It was additionally saved on SymPy’s
wiki, which made it much less accessible and
tougher to keep up within the context of SymPy’s full documentation.
Consequently, we determined to maneuver all contributor documentation
from the wiki to the principle SymPy docs. Moreover,
we rewrote the new
contributors information
to be extra inline with fashionable SymPy contribution practices, and to scale back the
components that solely clarify particulars on the right way to use Git and GitHub, which are actually
defined higher in different sources on the web.
A reside documentation preview construct was added to the SymPy CI so that folks
can simply view the way it seems to be as HTML. Whereas this
is a comparatively minor change in comparison with among the different issues talked about
right here, this has made issues considerably simpler for SymPy builders to evaluation
documentation adjustments.
To view a preview of the documentation, reviewers simply have to click on the
button within the standing checks for the pull request:
and they are going to be proven a rendered web page like:
Along with these organizational cleanups, the mission concerned writing new
documentation on deprecation, customized features, finest practices, and a glossary.
New Deprecation Coverage
SymPy as a symbolic arithmetic system is designed not simply as an interactive
piece of software program, but in addition as a library, which can be utilized as a dependency in
different Python initiatives. Consequently, we within the SymPy group take backwards
compatibility breakages in our API very severely. Any time the API adjustments in
a backwards incompatible approach, downstream customers of that API are pressured to
replace their code earlier than they’ll replace SymPy, which might be disruptive.
Beforehand, SymPy’s precise insurance policies on backwards compatibility breaks have been
imprecise, and generally builders would make breaks that ended up being
unnecessarily disruptive to SymPy’s end-users. A new deprecation
information has been
written that outlines a deprecation coverage. This information brings three new issues
to SymPy.
One – a transparent coverage on when backwards compatibility breaks ought to be made. The gist
is that deprecations ought to be
prevented,
and solely completed if completely crucial. There may be additionally now a coverage that every one such
public compatibility breaks ought to include a deprecation when potential, and
this deprecation ought to final at the very least a
12 months
earlier than being eliminated.
Two – a brand new SymPyDeprecationWarning class for deprecation warnings, which
offers far more person pleasant error messages. For instance
These warning messages give detailed info on what’s deprecated, what
customers can substitute their code with, what model the deprecation was added
in, and a hyperlink to an much more detailed web page of deprecation explanations.
Three – all lively deprecations are listed in a single web page.
This web page offers extra particulars about every deprecation than can be applicable
to place within the deprecation message, together with particulars on why every deprecation
was made. The web page additionally offers useful
info on the right way to silence deprecation warnings.
Information on Writing Customized Capabilities
SymPy comes with a whole lot of mathematical features built-in. Nevertheless it additionally
comes with a normal performance for customers to outline their very own customized
features. That is achieved by subclassing sympy.Operate and defining
numerous strategies to specify the symbolic habits. For instance,
SymPy now consists of an in depth how-to information on defining customized symbolic
features. This
information is beneficial to superior customers, but in addition this very same
technique is used to outline the features which might be included in
SymPy itself. So this information serves as each a information to superior end-users as
properly as a information to SymPy builders seeking to outline or lengthen one of many
features that comes with SymPy.
Information on SymPy Finest Practices
SymPy has many pitfalls, each for brand spanking new customers and superior customers. The brand new information
on finest practices
goes over some methods to keep away from these pitfalls.
For instance, one pitfall that many new SymPy customers run into is utilizing strings
as inputs to SymPy features, like
It is a lot better to outline symbolic variables and create expressions immediately,
like
The very best practices web page outlines why one ought to keep away from string inputs,
in addition to dozens of different finest practices
surrounding each primary and superior utilization of SymPy.
Glossary of SymPy Terminology
As a technical library, SymPy makes use of many phrases which have a selected
which means. If you’re not already conversant in SymPy, you won’t know what
these particular phrases imply, or not understand that they’ve a selected which means in
the context of SymPy.
For instance, the time period “resolve” is commonly used generically in arithmetic to
confer with any kind of drawback fixing. However within the context of
SymPy,
“resolve”
all the time refers back to the act of isolating a variable or set of variables
in an equation, like “resolve for x in x2 = 1.”
The brand new glossary
web page within the SymPy documentation defines numerous phrases as used within the context
of SymPy. That is helpful not solely as a standalone information, however it’s now simple for
different locations within the SymPy documentation to cross-reference these particular
phrases within the glossary in order that readers of these paperwork can perceive what
these phrases imply.
[ad_2]
