Skip to content

DOC: add timedelta64 signature - #14475

Merged
mattip merged 3 commits into
numpy:masterfrom
hypercubestart:add-timedelta64-signature
Sep 13, 2019
Merged

DOC: add timedelta64 signature#14475
mattip merged 3 commits into
numpy:masterfrom
hypercubestart:add-timedelta64-signature

Conversation

@hypercubestart

@hypercubestart hypercubestart commented Sep 11, 2019

Copy link
Copy Markdown
Contributor

fixes #14328

Added description of the arguments for np.timedelta64. I believe I added the correct documentation but any feedback is much appreciated.

Thanks!

mattip
mattip reviewed Sep 11, 2019
View reviewed changes
Comment thread doc/source/reference/arrays.datetime.rst Outdated
to complement datetime64.
to complement datetime64. The arguments for timedelta64 are a number,
to represent the number of units, and a date/time unit, such as
(D)ay, (M)onth, (Y)ear, (h)ours, (m)inutes, or (s)econds.

@mattip mattip Sep 11, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both datetime64 and timedelta64 also accept "NAT" (in any combination of upper and lower case) in place of the number for a "Not A Time" value. An example with that would be good and few words about it would be a nice addition. Also this page has a section "Differences Between 1.6 and 1.7 Datetimes". Please remove it.

@mattip mattip Sep 11, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you feel unsure about what I asked for let me know, it can be challenging to format some of the documentation.

@hypercubestart hypercubestart Sep 11, 2019

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattip I am having trouble generating the documentation. After installing all the dependencies, I successfully built numpy from scratch with python setup.py install.

However, when running make html, I run into
image

Is there a step I am missing?

@mattip mattip Sep 12, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You need to downgrade sphinx to 1.8.5, we don’t yet support sphinx 2.

@hypercubestart hypercubestart Sep 12, 2019

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@mattip sorry about the trouble, I am trying to learn as I go, but I ran into another problem when generating the docs with make html.

Can you please help me out? Here's the log file:

# Sphinx version: 1.8.5
# Python version: 3.7.1 (CPython)
# Docutils version: 0.15.2 release
# Jinja2 version: 2.10.1
# Last messages:
#   writing output... [  0%] dev/index
#   
#   writing output... [  0%] dev/releasing
#   
#   writing output... [  0%] dev/style_guide
#   
#   writing output... [  0%] docs/howto_build_docs
#   
#   writing output... [  0%] docs/howto_document
#   
# Loaded extensions:
#   sphinx.ext.mathjax (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/mathjax.py
#   alabaster (0.7.12) from /anaconda3/lib/python3.7/site-packages/alabaster/__init__.py
#   sphinx.ext.autodoc (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/autodoc/__init__.py
#   sphinx.ext.autosummary (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/autosummary/__init__.py
#   numpydoc (0.9.0.dev0) from /Users/andrewliu/Projects/numpy/doc/sphinxext/numpydoc/__init__.py
#   sphinx.ext.intersphinx (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/intersphinx.py
#   sphinx.ext.coverage (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/coverage.py
#   sphinx.ext.doctest (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/doctest.py
#   sphinx.ext.graphviz (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/graphviz.py
#   sphinx.ext.ifconfig (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/ifconfig.py
#   matplotlib.sphinxext.plot_directive (3.1.1) from /anaconda3/lib/python3.7/site-packages/matplotlib/sphinxext/plot_directive.py
#   IPython.sphinxext.ipython_console_highlighting (unknown version) from /anaconda3/lib/python3.7/site-packages/IPython/sphinxext/ipython_console_highlighting.py
#   IPython.sphinxext.ipython_directive (unknown version) from /anaconda3/lib/python3.7/site-packages/IPython/sphinxext/ipython_directive.py
#   sphinx.ext.imgmath (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/imgmath.py
#   sphinx.ext.linkcode (1.8.5) from /anaconda3/lib/python3.7/site-packages/sphinx/ext/linkcode.py
Traceback (most recent call last):
  File "/anaconda3/lib/python3.7/site-packages/sphinx/cmd/build.py", line 304, in build_main
    app.build(args.force_all, filenames)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/application.py", line 341, in build
    self.builder.build_update()
  File "/anaconda3/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 347, in build_update
    len(to_build))
  File "/anaconda3/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 412, in build
    self.write(docnames, list(updated_docnames), method)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 593, in write
    self._write_serial(sorted(docnames))
  File "/anaconda3/lib/python3.7/site-packages/sphinx/builders/__init__.py", line 604, in _write_serial
    self.write_doc(docname, doctree)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/builders/htmlhelp.py", line 246, in write_doc
    StandaloneHTMLBuilder.write_doc(self, docname, doctree)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/builders/html.py", line 731, in write_doc
    self.docwriter.write(doctree, destination)
  File "/anaconda3/lib/python3.7/site-packages/docutils/writers/__init__.py", line 78, in write
    self.translate()
  File "/anaconda3/lib/python3.7/site-packages/sphinx/writers/html.py", line 58, in translate
    self.document.walkabout(visitor)
  File "/anaconda3/lib/python3.7/site-packages/docutils/nodes.py", line 178, in walkabout
    if child.walkabout(visitor):
  File "/anaconda3/lib/python3.7/site-packages/docutils/nodes.py", line 178, in walkabout
    if child.walkabout(visitor):
  File "/anaconda3/lib/python3.7/site-packages/docutils/nodes.py", line 178, in walkabout
    if child.walkabout(visitor):
  [Previous line repeated 1 more time]
  File "/anaconda3/lib/python3.7/site-packages/docutils/nodes.py", line 170, in walkabout
    visitor.dispatch_visit(self)
  File "/anaconda3/lib/python3.7/site-packages/docutils/nodes.py", line 1912, in dispatch_visit
    return method(node)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/writers/html.py", line 886, in visit_math_block
    visit(self, node)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/ext/imgmath.py", line 323, in html_visit_displaymath
    fname, depth = render_math(self, latex)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/ext/imgmath.py", line 252, in render_math
    dvipath = compile_math(latex, self.builder)
  File "/anaconda3/lib/python3.7/site-packages/sphinx/ext/imgmath.py", line 139, in compile_math
    p = Popen(command, stdout=PIPE, stderr=PIPE)
  File "/anaconda3/lib/python3.7/subprocess.py", line 769, in __init__
    restore_signals, start_new_session)
  File "/anaconda3/lib/python3.7/subprocess.py", line 1516, in _execute_child
    raise child_exception_type(errno_num, err_msg, err_filename)
NotADirectoryError: [Errno 20] Not a directory: 'latex'

Also, the documentation https://numpy.org/devdocs/docs/howto_build_docs.html doesn't give information to download Sphinx version <2, so would it be a good idea to add it?

@mattip mattip Sep 12, 2019

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When I add a import pdb;pdb.set_trace() jsut before line 139 in imgmath.py, I can see command is ['latex', '--interaction=nonstopmode', 'math.tex']. Maybe you are missing latex? But then I don't understand how you get the error message NotADirectory. I am running on python3.6, maybe they changed the error in python 3.7?

Yes, we should document the version of sphinx we use, extra points for making it verifiable by the actual pip install command. Perhaps we should add a doc_requrements.txt like the test_requirements.txt

@hypercubestart hypercubestart Sep 12, 2019

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I removed the section "Differences Between 1.6 and 1.7 Datetimes" and added some info and examples on the "NAT" value.

Regarding the sphinx version, I added the information to use Sphinx version 1.8.3 <= 1.8.5. Is it also possible to check the Sphinx version within the Makefile?

@mattip

mattip commented Sep 12, 2019

Copy link
Copy Markdown
Member

Looks good, thanks. I restarted the win32 run and will merge once it passes.

@mattip
mattip merged commit ba32305 into numpy:master Sep 13, 2019
@mattip

mattip commented Sep 13, 2019

Copy link
Copy Markdown
Member

Thanks @hypercubestart. This is a nice cleanup and clarifiction

@hypercubestart
hypercubestart deleted the add-timedelta64-signature branch September 13, 2019 15:14
@mattip mattip mentioned this pull request Dec 3, 2019
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mattip mattip mattip left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

DOC: Missing signature for np.timedelta64

2 participants

@hypercubestart @mattip