Coder Social home page Coder Social logo

spyder-ide / spyder-docs Goto Github PK

View Code? Open in Web Editor NEW
33.0 15.0 282.0 194.97 MB

Documentation for Spyder, the Scientific Python Development Environment

Home Page: https://docs.spyder-ide.org

License: MIT License

Shell 0.75% Python 99.25%
spyder documentation python sphinx github-pages restructuredtext

spyder-docs's Introduction

Spyder Documentation

Spyder Docs - Documentation for the Scientific Python Development Environment

Copyright (c) 2009- Spyder Doc Contributors and others (see AUTHORS.txt)

License Build Check Lint Netlify Status pre-commit Nox OpenCollective Backers

Screenshot of documentation index page

Overview

This repository contains the documentation for Spyder, the Scientific Python Development Environment. You can view the live docs for current and past Spyder versions at docs.Spyder-IDE.org.

For more information about Spyder itself, please see our website and the main repo.

Building and Deploying

The docs are built with Sphinx and deployed with GitHub Actions to the docs.Spyder-IDE.org domain. Nox is used to automate setup, building and numerous other project tasks. The master branch contains the in-development docs for Spyder 5, while the frozen 4.x and 3.x branches retain the docs for Spyder 4 and Spyder 3.

Contributing

We welcome your contributions of corrections, additions and enhancements to these docs, as they are very much a work in progress, and we appreciate getting our broad community involved wherever possible. Its easy to build a local copy in one or two steps with Nox, or you can also just check your changes with our live build previews on PRs. Simply submit a PR with your changes and we'll be happy to review it; make sure to read our Contributing Guide in mind to ensure the process of getting your revisions integrated goes smoothly.

Thanks for your interest in Spyder and its documentation, and we appreciate your support of the project!

More information

Main Website

Online Documentation

Spyder Github

Development Wiki

Google Group

@Spyder_IDE on Twitter

@SpyderIDE on Facebook

Support Spyder on OpenCollective

spyder-docs's People

Contributors

bnavigator avatar cam-gerlach avatar ccordoba12 avatar dalthviz avatar do7py avatar ezio-melotti avatar goanpeca avatar hugovk avatar hyamanieu avatar hyounes4560 avatar isabela-pf avatar jitseniesen avatar juanis2112 avatar julienpalard avatar linus-albertus avatar lucyjimenez avatar map0logo avatar mmagnuski avatar p-tillmann avatar steff456 avatar vinisalazar avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

spyder-docs's Issues

Fix remaining layout issues with spacing and navigation header height

Issue Description

A few layout issues remain after #21 , including the navigation header not being the correct height, and lists and newline chars in rst not having the right vertical spacing in the output HTML. Thanks to @dalthviz for his help diagnosing and suggesting a solution to the latter.

Where is the relevant portion of the documentation located?

In the css layout template.

What would you suggest it be replaced with?

Change the navigation font size from 33.6px to 37px to match the main headings, and remove the borders around newlines while adding them around lists.

Jupyter Core Paths error

Issue Description

In ipythonconsole.rst

import jupyter_core
jupyter_core.paths.jupyter_runtime_dir()

On my install (anaconda latest) gives

AttributeError: module 'jupyter_core' has no attribute 'paths'

Should be

import jupyter_core.paths
jupyter_core.paths.jupyter_runtime_dir()

or even from terminal

jupyter --runtime-dir

Where is the relevant portion of the documentation located?

/doc/ipythonconsole.rst line 51

What would you suggest it be replaced with?

import jupyter_core.paths
jupyter_core.paths.jupyter_runtime_dir()

or from terminal

jupyter --runtime-dir

Other information

  • Is the problem specific to documentation for a particular version of Spyder?

No

  • Are you planning on submitting a Github pull request with a suitable change?

I can

  • Anything else you'd like to add?

No I'm good

Implement a modern Sphinx html theme that matches our website

Issue Description

Right now, our current theme is very dated and quite horribly at odds with that of our website, so it needs to be updated. Therefore, we wanted to solicit everyone's feedback as part of that process. So...

@spyder-ide/core-developers @spyder-ide/junior-developers

While I have a specific proposal as a starting point, its ultimately up to the consensus on what we go with, built-in or third party, so long as it is straightforward to install and use the theme, and it is under an appropriate license. Let's hear your feedback and/or suggestions!

My Proposal

As a starting point, I took the built-in Alabaster sphinx theme and heavily customized it with the supported options to fit our needs, which you can view as PR #12 . Out of the built in sphinx themes, I found it to match the look and feel of our website the best (particularly once the font was changed to the same one the latter uses), and it is also one of if not the most modern, well-supported, and customizable, with many extra and advanced features most of its counterparts lacked.

This allowed me to match the font (Open Sans) and exact color palette (same light and dark grey colors, and a hint of the same out of the tube red as the accent color) as the logo and website, and also allowed for adding a github watch/star widget and fork banner, and a dynamic Travis build status widget like our doc has, as well as extra links to all of major web properties (which could also be used in the future to easily host a link to an alternate (Spyder 3/4) edition of the docs if/when we start deploying those.

In any case, aside from the above, it is undeniably convenient, reliable and future proof to use a core built-in theme rather relying on something third-party. However, if there is a substantially better third party option available that is straightforward to get working reliably, then we can certainly use that instead. Therefore, I welcome your feedback on this baseline, and look forward to your further suggestions. Thanks!

image

image

image

Basic documentation for Spyder plugins

@goanpeca commented on Wed Jan 20 2016


@Nodd commented on Tue Jun 21 2016

Added some docs:
https://github.com/spyder-ide/spyder/wiki/User-plugins
https://github.com/spyder-ide/spyder/wiki/Writing-Plugins
It's very basic and inspired from the old googlecode site: http://web.archive.org/web/20141228215028/https://code.google.com/p/spyderlib/wiki/SpyderPlugins


@ccordoba12 commented on Tue Jun 21 2016

Thanks @Nodd!!


@ccordoba12 commented on Sun Aug 13 2017

This can be improved once we merge the split-plugins branch.


@ccordoba12 commented on Fri Oct 12 2018

Moving to spyder-docs.

Remove the old manpage and the relevant section from conf.py

Issue Description

Remove the manpage and the relevant section in conf.py, added to meet Debian standards, that essentially duplicates information from spyder --help, only is on master, and could lead to potential merge conflicts in the future, and is just unneeded cruft.

Where is the relevant portion of the documentation located?

manpage.rst and manpage section of conf.py

What would you suggest it be replaced with?

Deleted.

Other information

  • Is the problem specific to documentation for a particular version of Spyder?

master only for some reason.

Describe how to launch Spyder after installing via various methods

Issue Description

As noticed by multiple users on our Gitter, our documentation currently doesn't include any mention of how to actually launch Spyder after install via various means (pip, conda, etc). Therefore, we should mention such in our install docs.

Where is the relevant portion of the documentation located?

Installation doc

Add a link checker to the CI tests

Issue Description

Currently, several links for our current docs are broken, and nearly half are perma-redirected. It should be fairly simple to add a link checker, namely sphinx's built in make linkcheck, to catch these issues as they happen. I plan to do it as soon as we can close #13 . It should be quick to do once that happens, but can easily be bumped from the critical path for the IPR if needed since part of that previous PR involves running it locally and fixing the problems detected.

Describe how to install Spyder 4 betas

This was mentioned in Gitter:

Hello! I was wondering if there is a way I can install the Spyder 4 beta? I was looking around online (github, documentation, etc) and couldn't find any info. Some of the features that are in the beta (specifically indentation guides) would be insanely helpful for the class I'm in!

I agree completely that it's nearly impossible (if you're not subscribed to our mailing list) to discover how to install our betas.

@CAM-Gerlach, I don't know if this should go here or a blog post about beta1. What do you say?

Baseline copyediting and correctness pass to update existing doc content

Issue Description

Currently, quite a few details and references in our documentation are out of date (e.g. to Mercurial support, Python(x, y), the non-IPython console, etc), and a number of grammar, style, and syntax problems exist. In this issue, I propose a baseline sweep through the existing stuff to clean up such easy to resolve items to ensure a baseline of textual quality for our initial public release of the new docs.

Task List

  • Decide on conventions and create internal style guide (public version to be released as a separate issue/PR)
  • Initial cross-file changes
    • Use consistent capitalization, marker characters, naming scheme, and structure for titles, headings and subheads, and add additional
    • Rename "Related Plugins" section to "Related Components", make a L3 subhead, and cleanup/add additional links
    • Harmonize all topic names to be bold and title case in first sentence
  • Index page
    • Replace outdated content with heavily revised text from readme
    • Make one sentance per line
    • Re-organize and cleanup toctree
  • Baseline copyediting and corrections per file
    • Remove/correct outdated information
    • Copyedit text for better prose
    • Harmonize line breaks to one per sentence to make both editing and reviewing changes much easier, and git much cleaner and more effective
    • Add minimal necessary additional text/items to fill out at least one short section per doc
  • Add a few additional brief descriptions to bare links in overview
  • Fix numerous bad links and add https where possible
  • Harmonize formatting of elements/directives to conform to style guide
    • Admonitions
    • Set two blank lines before all headings and overbar format for L2
    • File names/paths
    • Keyboard shortcuts
    • GUI elements
    • Menu/preference selections
    • Code blocks

Update Development Version Installation Instructions For Spyder 4 As Default

Issue Description

Because Spyder 4 is the default version in the repository, some instructions that distinct version 3 and 4 are no longer necessary.

Where is the relevant portion of the documentation located?

In doc/installation.rst there is a long note about how to install development environment for spyder 4:

#. Install the Spyder `requirements`_.

   The recommended and easiest way to do this is with ``conda`` (although experts may prefer ``pip``). In a fresh environment (``conda create -n your-name-here -c conda-forge python=3``, then ``activate`` it), run the following:

   .. code-block:: bash

      conda install -c conda-forge/label/beta spyder=4.0.0b1
      conda install -c conda-forge python-language-server
      conda remove spyder

   This installs all of Spyder's dependencies into the environment along with the stable/packaged version of Spyder, and then removes Spyder itself.

   .. note::

      Following the separation in v3.3 of Spyder's console code into its own package, ``spyder-kernels``, you'll need to have the corresponding version of it available—``0.x`` for Spyder 3 (``3.x`` branch), and ``1.x`` for Spyder 4 (``master`` branch).
      The above procedure will install the ``0.x`` version; to test the ``master`` branch (Spyder 4), you'll need to install the corresponding ``1.x`` version of ``spyder-kernels``.
      This can be done via two methods: installing the ``1.x`` version via ``conda``:

      .. code-block:: bash

         conda install -c spyder-ide spyder-kernels=1.*

      or ``pip``:

      .. code-block:: bash

         pip install spyder-kernels==1.*

      (and using the same respective command, replacing ``1`` with ``0``, to switch back to the Spyder 3 version), or by ``clone``-ing the `spyder-kernels git repository`_ to somewhere on your path and checking out the appropriate branch (``0.x`` or ``master``) corresponding to the version of Spyder (3 or 4) you would like to run, and running the commend ``pip install -e`` at the root.
      For any non-trivial development work, keeping two separate virtual environments (with ``conda-env`` or ``venv``) for Spyder 3 and 4 makes this process much quicker and less tedious.

What would you suggest it be replaced with?

Delete these notes and fix the commands to proper ones.

Other information

  • Is the problem specific to documentation for a particular version of Spyder?

  • Are you planning on submitting a Github pull request with a suitable change?
    Yes.

  • Anything else you'd like to add?

Update installation instructions to account for new spyder-kernels dependency

Issue Description

Per spyder-ide/spyder#7337 (and ultimately due to spyder-ide/spyder#7306 ), installation instructions will need to be updated to clarify the need for an additional dependency, spyder-kernels, which will in turn need to be for the correct version of spyder (3.x or 4/master).

Where is the relevant portion of the documentation located?

Installation instructions docs, specifically installing from source and setting up a development environment sections.

What would you suggest it be replaced with?

Reminding the user to install the dependency, and the different procedure for master vs. 3.x.

Other information

  • Is the problem specific to documentation for a particular version of Spyder?

Spyder 3.3 onward, and particularly for work on master.

Remove dependencies information from docs

Issue Description

Information of dependencies is not necessary anymore because they are mentioned in dependencies.py plus as they change frequently it makes it harder to update in the docs

Where is the relevant portion of the documentation located?

What would you suggest it be replaced with?

Other information

  • Is the problem specific to documentation for a particular version of Spyder?

  • Are you planning on submitting a Github pull request with a suitable change?

  • Anything else you'd like to add?

No descriptions/explanations for some bullets in the Overview

Issue Description

Many bullets in the Overview, as well as some sections/headers elsewhere, have no description at all. Therefore, we want to have at least a basic explanation of each before we release the docs publicly, as this is fairly low hanging fruit and will have a pretty high impact to effort ratio.

Where is the relevant portion of the documentation located?

Primarily the Overview, but content should be opportunistically added elsewhere when desperately needed and easy to do.

What would you suggest it be replaced with?

At least a few sentences/a short paragraph of explanation for each, as appropriate.

Update installation guides

Issue Description

Where is the relevant portion of the documentation located?

What would you suggest it be replaced with?

Other information

  • Is the problem specific to documentation for a particular version of Spyder?

  • Are you planning on submitting a Github pull request with a suitable change?

  • Anything else you'd like to add?

Update screenshots to those from modern Spyder, and add additional shots of different Main Window layouts, etc

Issue Description

Many of the screenshots we currently have are from very old versions of Spyder, running on vintage OS versions and have a lot of chrome around the actual content. This is both potentially inaccurate and confusing to our current users, and does not present a good impression to potential new ones. Therefore, this should be speedily corrected before the initial public release.

As part of spyder-ide/spyder-website#75 I will be taking some screenshots anyway, so I may as well hit on what is needed here. Specific work items:

  • Add "default" master screenshot to Index and Overview pages
  • Add ~3 additional screenshots with various panel, layout, and color arrangements to the Overview page
  • Add/update panel screenshots for each respective page

Where is the relevant portion of the documentation located?

Primarily in the sections on the core/older features, such as the editor and console, and in sections not referring to a specific feature.

What would you suggest it be replaced with?

More and better screenshots from modern Spyder.

Mention how to run cells

I couldn't find a mention about how to run cells in our docs, even though we mention how to create them. This is a serious issue we should solve as soon as possible.

Describe how new Code Style and Docstring Style options work in Spyder 4

Issue Description

Per the discussion in spyder-ide/spyder#9231 and specifically @ccordoba12 's request, we should describe how to use the Code and Doc Style settings in Spyder 4's preferences, particularly the interaction between the "Show" and "Ignore" fields. This would probably be best worked into an expanded Editor article, specifically a discussion on the various LSP-provided features the editor offers (Code Analysis, Hints, Calltips, Completion, etc.); otherwise; it would be part of a broader article/docs section that discusses Spyder's preferences in more detail (which I hope to add at some point).

Add a full guide detailing the common structure, technical standards, style conventions, and writing guidelines

Issue Description

Currently, we have only a very minimal set of standards, conventions and guidelines in our contributing guide; this proposes adding, likely as a separate document with a few elements from contributing merged in, a comprehensive outline of the common document and file structure, the technical standards to be adhered to, and the style conventions to follow for rst and prose, and guidelines to writing accessable technical documentation. I've written up a copy locally, but it is still in draft form and may still change before #13 is completed, and also needs some polish and clarification for public release. Therefore, I plan to do this as one of the first tasks after the initial public release.

Also, as part of this should update PR (and Issue?) templates with "check style guide", and should also add how to create a fork, branch, and submit PR to the contributing guide, and any other build instructions.

Remove link to Docs in top navbar

Now you see

Home Blog Docs

to the right of the navbar, but it should show instead

Home Blog

because you can reach the root of our docs by clicking

Spyder | Docs

@dalthviz, this is an easy one for you.

Clarify remote kernel connection process (how to find connection file and enter credentials)

@jsh9 commented on Sat Sep 08 2018

Problem Description

I am following the steps in the documentation (https://docs.spyder-ide.org/ipythonconsole.html#connect-to-an-external-kernel) to try to open up an ipython kernel on my remote computer and then access it from my local computer.

I used ipython kernel on my remote computer, and saw the following message on the terminal:

NOTE: When using the `ipython kernel` entry point, Ctrl-C will not work.

To exit, you will have to explicitly quit this process, by either sending
"quit" from a client, or using Ctrl-\ in UNIX-like environments.

To read more about this, see https://github.com/ipython/ipython/issues/2049


To connect another client to this kernel, use:
    --existing kernel-17928.json

This step in the documentation ("Make sure to copy the connection file (runtime-dir/kernel-pid.json) to the machine you’re running Spyder on (if remote) or note its location (if local).") requires me to find the location of kernel-17928.json, but I don't know where this json file is on my remote computer.

Versions

  • Spyder version: 3.3.1 (remote) and 3.3.0 (local)
  • Python version: 3.6
  • Qt version: 5.9.6 (remote) and 5.6.2 (local)
  • PyQt version: 5.9.2 (remote) and 5.6.0 (local)
  • Operating System name/version: macOS (remote), Windows (local)

@ccordoba12 commented on Sat Sep 08 2018

Moving to the right repo.

Make content width adaptive to window size instead of cutting off text

Issue Description

Currently, our docs content (and sidebar) is a fixed width, which results in hard cutting off of the text in many scenarios, and even worse, scrolling past the edge doesn't render the missing text. This forces us to either exclude large classes of user setups/use cases from being able to view the docs properly, or use an unreasonably narrow content width.

image

The solution is to make the width of the docs content (and perhaps the sidebar, to a lesser extent) adaptive; i.e. starting at 1200 px max total width and then reducing the width and soft-wrapping the text if the window is smaller than that; also, we can pin the sidebar to one side to make the margins more even. Basically, something like this Github books output mentioned by @ccordoba12 .

Hopefully its possible to do in CSS but if not, then some simple JS perhaps. I'm guessing @dalthviz would be the one to do this?

Update installation instructions in master to reflect PyLS as a dependency

Issue Description

Related to spyder-ide/spyder#7822 , in turn part of spyder-ide/spyder#7724 , we need to ensure our installation instructions in master (Spyder 4) reflect the addition of python-language-server as a dependency and removal of jedi/rope/pycodestyle/pyflakes, and are otherwise up to date for Beta 2.

Where is the relevant portion of the documentation located?

Installation guide; installing from source/development build sections; check other sections for continued correctness (particularly Anaconda and pip).

Add baseline Profiler documentation

Issue Description

Currently, all the main Spyder panes have at least a short page of documentation dedicated to them (with the outline covered in the Editor's doc, and the breakpoints pane discussed in Debugging)—except for the profiler, a much more significant feature than many of these. Therefore, we should include at least a stub length doc similar to the others (e.g. static analysis) for completeness. This would be done after I actually push the PR for #13 , and then after I'd merge the former I'd rebase and add the profiler links to the appropriate places in the other docs.

Many sections need to be rewritten to be more explanatory ("how") than expository ("what")

Issue Description

In a number of sections of the documentation, various features (e.g. splitting the editor, to name one example) are outlined and their purpose detailed, but there is little to no information about how to actually activate and use them from a technical perspective. Therefore, the documentation as a whole should be re-written where practicable to focus more on explaining the "how", and less on just showcasing the "what", keeping in mind this is supposed to be a technical help manual, not promotional material (like the website).

Where is the relevant portion of the documentation located?

Throughout; the overview is 100% this which isn't entirely bad, but each feature could use at least a brief explanation on how to open/activate/use it; many of the feature sections say what Spyder can do but not how to actually do it as a user.

What would you suggest it be replaced with?

More explanatory, step by step guidance and explanations.

Remove the obsolete Python Console doc, add any relevant parts and links to the IPython console docs

Issue Description

The current docs have an entire doc page about the old Python console that is no longer included with Spyder. Therefore, I will remove this, update any links pointing to it and direct them to IPython Console docs instead, and move any remaining relevant content over there. This is already complete as part of #22 , but as that got closed it will be in the replacement PR, as it is a prequisite/blocker for #14 .

Where is the relevant portion of the documentation located?

console.rst

What would you suggest it be replaced with?

Nothing; directly, but effectively the IPython Console.

Decide on and implement a common heading and body font size between the docs and the blog

Issue Description

To summarize, the initial idea behind of #19 was to harmonize the banner and the fonts used between the docs and the website (really, with the blog rather than the mainpage with respect to the latter as it stands currently, due to the sans font for the headings). Following some requested changes, the font sizes for the doc headings and body diverged from that used on the blog. However, as discussed in #21 and elsewhere, as the current font sizes on the blog is on the larger end of the acceptable range, while the docs could still tolerate a bump, and its best to keep them consistent, it would probably be a good idea to re harmonize them, so we can discuss that here.

Where is the relevant portion of the documentation located?

The CSS layout file.

What would you suggest it be replaced with?

Perhaps the best solution is to bump the doc body font up one more size to 16.8px, and bump the blog down one to that (from 18px) as well. It should be a good compromise between the two, and will also match the sidebar main font size as well. Accordingly, the top/main and sub heads of the blog could also be brought down to 37px and 27.7px from 48px and 39.6px respectively to match as well, as they are quite big as is, although both (the docs and the blog) and the could be brought to a size a little bigger than the current docs if the latter is a bit too small for the blog.

@ccordoba12 and @dalthviz , your thoughts?

Inform/submit PRs to external parties to update Spyder website and doc links

Issue Description

Implicitly blocked by the other I.P.R. issues; this should be done last, of course.

Some of these are even still using the old Google Code "spyderlib" link

Parties to contact:

Additional places with "projects using xxx" pages where should add our link(s):

Out of scope?

  • Lektor OUT OF SCOPE (in final stages of completion, but well out of scope for this issue)

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.