Remove the 'Without make' section #327
Conversation
Firstly, 'Without make' makes no sense because we can pass a parameter to the ``make`` command, for example, ``make html``, or ``make latexpdf`` and we will get the same result. Secondly, We have to provide an easy way for the developers which want to generate the documentation.
|
Hi all, I just created this PR, but I prefer that we discuss before an eventual merge. @Mariatta and @ned-deily |
|
Why removing it? I can imagine some distro without |
|
Are you sure that using I suggest 3 different ways to deal with this (depending on the answer of the previous question):
|
We only support building Python itself with IMO, a primary purpose of the devguide is to provide one standard way to accomplish a task, in this case, produce the most commonly used docs, the HTML version. It is not intended to be a reference guide for the whole doc build process. The information about using sphinx-build directly appears to be duplicated from that in Doc/README.rst. How about just replacing the without make section with a reference to the README.rst? |
There was a problem hiding this comment.
Please close this PR and leave this little section alone. It hurts nothing. [Edit: see next comment for revised suggestion.] It tells a developer exactly the command needed to build the docs in a customized OS shell script.
Here, for example, is my F:/dev/dmake.bat.
echo off
if "%1" EQU "36" cd f:\dev\36\Doc
if "%1" EQU "37" cd f:\dev\37\Doc
if "%1" EQU "38" cd f:\dev\3x\Doc
C:\programs\python36\scripts\sphinx-build -bhtml . build/html
cd ..
call python.bat -c "from idlelib.help import copy_strip; copy_strip()"
When I first wrote my script, I tried calling make.bat to call sphinx-build but that did not work so I had to call sphinx-build directly.
There is a separate issue that sphinx-build seems to no longer work for me either in the above or in make.bat. When I run the .bat file above, I get a failure message. When I run make.bat, the failure message does not appear, and it says "Build succeeded." -- when it also failed. I prefer the former. I will ask on core-mentorship about the failure.
|
Ned is correct that this section is indeed a copy. It can be criticized for repeating 'install sphinx' (already said above) and being too general (the topic is building the html version). I suggest condensing it to just two lines before the 'See also' note, with the specific command. To build html without make, run the following in the Doc directory: I suggest putting this before 'see also' because 'see also' applies to this as well as the make stuff. |
|
But people can always read the |
|
Reading the windows make.bat is a real pain and extracting the single command needed for developers to check their docs patches is not completely trivial. Make.bat also merges blurbs into the news log, which is irrelevant unless one uses rst makeup. |
|
OK, so it sounds like we are not going to reach consensus beyond "keep it as small as possible", so let's aim for that. |
|
Hi @matrixise, Let's get the PR completed finished off. I have two suggestions below if you would like to add them. If you are too busy post-PyCon to do so, I will happily add them. Just let me know... Thanks! I left a message on the open issue #324: Next actions:
|
|
@willingc when you have time, just check my new commit. PS: I am really sorry for this very late answer :/ |
documenting.rst
Outdated
| ------------ | ||
|
|
||
| Install the Sphinx, blurb, and python-docs-theme packages from PyPI. | ||
| Sometimes we directly want to execute the sphinx-build tool, in this case, you can |
There was a problem hiding this comment.
"tool instead of through make (although the latter is still the preferred way). In this case,"""
documenting.rst
Outdated
|
|
||
| Install the Sphinx, blurb, and python-docs-theme packages from PyPI. | ||
| Sometimes we directly want to execute the sphinx-build tool, in this case, you can | ||
| use the following command line but before you have to install the Sphinx, blurb, |
There was a problem hiding this comment.
"command line from the Doc directory (make sure to install Sphinx, blurb, and python-docs-theme from PyPI)::" and link to their PyPI pages. This then means you should remove line 1575.
|
@brettcannon just updated, thank you for your review. |
|
Thanks @matrixise for finishing this off. Sorry I missed the review as I was taking some vacation 👍 |
Explain how to use `sphinx-build` via the command line.
Firstly, 'Without make' makes no sense because we can pass a parameter to the
makecommand, for example,make html, ormake latexpdfandwe will get the same result.
Secondly, We have to provide an easy way for the developers which want
to generate the documentation.