8000 spin document build problems · Issue #24713 · numpy/numpy · GitHub
[go: up one dir, main page]
Skip to content

spin document build problems #24713

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
charris opened this issue Sep 14, 2023 · 8 comments
Closed

spin document build problems #24713

charris opened this issue Sep 14, 2023 · 8 comments
Labels
04 - Documentation
Milestone
1.26.0 release

Comments

@charris
Copy link
Member
charris commented Sep 14, 2023 •
edited
Loading

Running python -m spin docs --build

  1. The html files are not zipped (see doc/Makefile). The zip files are needed for numpy.org.
  2. Couple of sphinx complaints
  reading sources... [100%] release/1.21.5-notes .. user/whatisnumpy                                                                     
  /home/charris/Workspace/numpy.git/doc/source/reference/random/examples/cython/setup.py.rst:4: WARNING: 
  Include file '/home/charris/Workspace/numpy.git/numpy/random/_examples/cython/setup.py' not found or reading it failed
  looking for now-outdated files... none found
  pickling environment... done
  checking consistency... done
  preparing documents... done
  /home/charris/Workspace/numpy.git/doc/source/user/building.rst:48: WARNING: undefined label: 'scipy:using-pkg-config-to-detect-libraries-in-a-nonstandard-location'
  /home/charris/Workspace/numpy.git/doc/source/user/building.rst:141: WARNING: unknown document: 'scipy:cross_compilation'

The whole random module was taken from main, so should probably have fixes for using meson.

On the plus side, the correct numpy version (1.26.0rc1) is built and used.
@charris
Copy link
Member Author
charris commented Sep 14, 2023 •
edited
Loading

The first sphinx complaint looks fixable by copying doc/source/reference/random/examples/cython from main.

@rgommers
Copy link
Member

That command is for regular building of the html docs. I believe the release command was always make dist. Either way, after spin docs --build I think you can run these commands locally to get a zip file right now:

build/dist.tar.gz: real-dist

real-dist: html-build
	cp -r build/html build/dist
	cd build/html && zip -9r ../dist/numpy-html.zip .
	cd build/dist && tar czf ../dist.tar.gz *
	chmod ug=rwX,o=rX -R build/dist
	find build/dist -type d -print0 | xargs -0r chmod g+s

I can have a look at integrating it into the spin docs CLI. How about spin docs --dist as the command?

I'll have a look at fixing up the warnings as well.

rgommers added a commit to rgommers/numpy that referenced this issue Sep 15, 2023
@rgommers
DEV: improve spin docs command
4893b24 
Explain how to build a zipfile of the html docs for release purposes.
Remove --install-deps, as that is bad practice and `pip` invocations
for dependencies should not be present in this CLI.

Closes numpygh-24713
@rgommers rgommers added this to the 1.26.0 release milestone Sep 15, 2023
@charris
Copy link
Member Author
charris commented Sep 15, 2023 •
edited
Loading

How about spin docs --dist

Sounds good. The make merge-doc command is what I use to update numpy.org and it runs make build/dist.tar.gz. I'd like to get rid of the Makefile, so if there were a single command that replaced merge-doc I would be happy.

EDIT: For now we could just fix the Makefile so that merge-doc runs $(PYTHON) -m spin docs -dist.

@rgommers
Copy link
Member

See my linked PR. For merge-doc, this should work already: spin docs merge-doc.

I'd like to get rid of the Makefile

Hmm, I wasn't planning on touching that. Translating the Makefile line by line into Python code in .spin/cmds.py will probably result in running the same commands through subprocess calls.

@charris
Copy link
Member Author
charris commented Sep 15, 2023

The important documentation is RELEASE_WALKTHROUHGH.rst :)

@charris
Copy link
Member Author
charris commented Sep 15, 2023

Translating the Makefile line by line into Python code

Most of it is never used, all we need is the ability to make docs.

@rgommers
Copy link
Member

Most of it is never used, all we need is the ability to make docs.

Maybe let's just delete the parts we don't need for now?

The important documentation is RELEASE_WALKTHROUHGH.rst :)

Ah, I forgot. Would be nice if we'd delete HOWTO_RELEASE.rst. I'm about to sign off, I hope the added docs are enough for you right now? Basically and make XXX you can replace by spin docs XXX.

@rgommers
Copy link
Member

Fixed by gh-24721 (main) and gh-24718 (1.26.x), closing.

charris pushed a commit to charris/numpy that referenced this issue Nov 11, 2023
@rgommers @charris
DEV: improve spin docs command
f79308a 
Explain how to build a zipfile of the html docs for release purposes.
Remove --install-deps, as that is bad practice and `pip` invocations
for dependencies should not be present in this CLI.

Closes numpygh-24713
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
04 - Documentation
Projects
None yet
Milestone
1.26.0 release
Development

No branches or pull requests
2 participants
@charris @rgommers
0