For a fast preview, I want to build only one file and not all the project. It is possible with sphinx ?
Recently I do something like :
sphinx-build -b html documentation/ doc_html
Sphinx already uses incremental build by writing output files only for new and changed source files. But before that, full build is needed because Sphinx needs to know where the internal links are pointing and where they are referenced from.
Related
Python Docstring Image Embed
In a Python docstring I have a reStructuredText directive to display an image:
.. image:: ./images/code_quality.png
Instead of the image, I get a small icon and a path:
_images/code_quality.png
Screen clip of link shown instead of the image I want to show.
I have tried this also:
.. image:: images/code_quality.png
And this:
.. image:: https://imgs.xkcd.com/comics/code_quality.png
:alt: code_quality
Using figure instead of image simply centers the same output.
.. figure:: images/code_quality.png
It also doesn't work if I take it out of the docstring and put it in an .rst file instead.
The image is copied into the _static directory as it should be by Sphinx. Any other formation of the link throws an error. I have two empty lines before and after the directive.
All other docstrings render correctly, including the rest of the docstring that contains the image link. I have no other images to render, but I did try this once before in another module and it did not work then either.
I'm using autodoc to scan the Python modules' docstrings. I am on Windows 10 and Chrome is my primary browser. It does not work on any other browsers I've tried either.
There are suggestions to look at this answer:
Is it possible embed pictures into docstring in Python?
I am using the image directive.
My path is correct.
Neither the relative path nor the full path lead to a rendered image.
I am not using PyCharm for this project, I am using VS Code.
My documentation renders fine apart from the image issue.
Shell output on make:
\docs>make html
Running Sphinx v2.4.4
loading translations [en]... done
making output directory... done
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 11 source files that are out of date
updating environment: [new config] 11 added, 0 changed, 0 removed
reading sources... [100%] user_guide
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] user_guide
generating indices... genindex py-modindexdone
writing additional pages... searchdone
copying images... [100%] images/code_quality.png
copying static files... ... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.
The HTML pages are in build\html.
The image portion of the HTML output is:
<img alt="_images/code_quality.png" tedc="_images/code_quality.png" />
('tedc' is the name of the app as I defined it in the project's root setup.py module.)
GitHub Repo
This is my attempt to recreate the issue of image directives not working properly in Sphinx by creating a project that is structured the same general way my production project is structured.
My production code is called from root, with modules living in packages.
My documentation lives in a docs directory, the same as presented here.
I use a virtual environment, same as here.
I use a great many more libraries than are used here.
I'm using Python 3.8.2
I found nothing in the exercise that would help explain why the image directives are not working in my production code. My production code uses the same directives.
After I tried to reproduce this issue and failed to do so, I suggested that the OP should try deleting the virtual environment and docs build directory, and recreate their virtual environment, install requirements, and build docs again. This resolved the issue.
Actually, I want to create a plug and play architecture in Python Django. I have a different kind of scrapers and I am writing more scrapers too. Whenever I build a new scraper I have to again publish my repo in production. What I need I just want to plug that new scraper without actually again deploying my code. I have already used the GitHub versioning system but I am in need of a more clean way. Thanks in advance.
What you should be doing is Generating the Setup.py File which would automatically set it up as a package thus, When the User would run the Setup.py File,
It would deploy it as a package. Second Thing is you can create a Package out of It with the tools already provided by Python to create a Package of an App in Django.
Packaging a Python Script:
https://the-hitchhikers-guide-to-packaging.readthedocs.io/en/latest/quickstart.html
https://pythonhosted.org/an_example_pypi_project/setuptools.html
For Django, Follow below Steps:
Initilize it with a ReadMe File
Initilize it with a MANIFEST.in to include the text files and static files in our package
run python setup.py build
Reference: https://www.pythoncentral.io/package-python-django-application-reusable-component/
Now Simply Use it anywhere You Wish making it a Reusable App!
Reference for a Package Settled Up:
https://github.com/smfai200/rebound
I'm trying to understand how to make Sphinx work.
I'm not Python developer - instead, I want to use reST and Sphinx for general purpose texts.
So, I have Python, DocUtils and Sphinx installed. I have test.rst inside C:\Test\ directory. Then, I launch cmd.exe in this directory and type: sphinx-quickstart. Then, I press Enter multiple times for default presets.
Then I have some new files in this folder, including make.bat. Then, I run: make.bat html. Then, the Sphinx HTML files are created. But when I open index.html - I don't see the contents of my original test.rst.
So, how to make it work?
(Despite the completely identical title, my question is not a duplicate of this in any sense).
You must add test to the toctree directive in your index.rst.
.. toctree::
:maxdepth: 2
test
See the documentation of Directives for additional options and syntax.
I am trying out Sphinx for generating documentation for a Python project. Just to make sure I can actually make it work, I have made a test project to try it out on: https://github.com/ThomasA/sphinxtest.
I have run sphinx-quickstart in the root of this repository. In the following questions, I specified 'doc' as the documentation root, named the project 'sphinxtest', entered 'Thomas Arildsen' as author, answered 'y' to the 'autodoc' option, and selected the default setting for everything else.
I expected the 'autodoc' option to cause the generation of a file 'amodule.rst' in the 'doc' folder. However, this does not get generated. I am puzzled by this. I thought this was what the 'autodoc' option was supposed to do and what I have seen examples of others apparently achieve with it. Sphinx completes without any error messages, so it seems to be doing what it thinks it should do. So, what could I be doing wrong?
I am using Sphinx v. 1.5.6 and Python 3.5.3, all installed with Anaconda.
autodoc does not generate the .rst source files.
Instead first use sphinx-apidoc to generate the source files. Then run Sphinx to make your documentation.
An alternative to Percy's answer is autoapi written by Carlos Jenkins. He provides a Sphinx extension that generates the ReST files per documentation generation. You can configure the output ReST by modifying a template file.
https://github.com/carlos-jenkins/autoapi
I use Sphinx to document my code, which is a collection of Python modules. The autogenerated documentation that's made by scrubbing my source code is fine, but when I click on the "code" link that links directly to the HTML pages containing my package's sources that Sphinx generates, an older version of my code is shown.
I've tried deleting my Sphinx generated documentation, uninstalling the package from my own site-packages folder, and deleting everything in my build folder. I can find absolutely no files that match Sphinx's output - it's old, and I'm not sure where it's coming from. Does anybody know how to get Sphinx to put my new code in the documentation?
As I said, the autodocumentation works fine, so it's obviously parsing my code on some level. So why is the pure text different from the autodocumentation?
Sphinx caches (pickles) parsed source files. The cache is usually located in a directory called .doctrees under the build directory. To ensure that your source files are reparsed, delete this directory.
See http://www.sphinx-doc.org/en/stable/man/sphinx-build.html#cmdoption-sphinx-build-d.
Pass the poorly documented -a option to sphinx-build.
Doing so effectively disables all Sphinx caching by forcing Sphinx to rebuild all output documentation files (e.g., HTML in the docs/build/ subdirectory), regardless of whether the underlying source input files have been directly modified or not. This is my preferred mode of operation when locally authoring Sphinx documentation, because I frankly do not trust Sphinx to safely cache what I expect it to. It never does.
For safety, I also:
Prefer directly calling sphinx-build to indirectly invoking Sphinx through makefiles (e.g., make html).
Pass -W, converting non-fatal warnings into fatal errors.
Pass --keep-going, collecting all warnings before failing (rather than immediately failing on the first warning).
Pass -n, enabling "nit-picky mode" generating one warning for each broken reference (e.g., interdocument or intrasection link).
Pass -j auto, parallelizing the build process across all available CPU cores.
I have trust issues. I'm still shell-shocked from configuring Sphinx for ReadTheDocs three all-nighters ago. Now, I always locally run Sphinx via this command (wrapped in a Bash shell script or alias for convenience):
$ sphinx-build -M html doc/source/ doc/build/ -W -a -j auto -n --keep-going
That's just how we roll, Sphinx. It's Bash or bust.