ericholscher / sphinx-tutorial Goto Github PK
View Code? Open in Web Editor NEWAn opinionated tutorial on Sphinx.
An opinionated tutorial on Sphinx.
Re last issue submitted by me. Having examined the tutorial code in detail I have re-edited the file 'pycon-sphinx-tutorial/crawler/src/main.py' so that when I run 'make.html' the build no longer fails and 'api.rst' displays correctly.
What I had to do was to modify the line 'from utils import log, should_ignore' to 'from crawler.utils import log, should_ignore'. The context for this change is that I had previously added 'pycon-sphinx-tutorial/crawler/src', the directory containing 'utils.py', to the Python sys.path so as to import 'log' and 'should_ignore' from the module now renamed crawler.utils.
without adding
sys.path.insert(0, os.path.abspath('../src/crawler/'))
to conf.py I get following error message:
WARNING: autodoc: failed to import module 'main' from module 'crawler'; the following exception was raised:
No module named 'utils'
Think this should be added in the Tutorial because it took me one hour to find out while doing Step 2
Can you provide a pdf with the two pages of the cheatsheet?
The current pngs are not in a high resolution (which shows when printing) and two separate files makes it more difficult to print it double sized. A proper pdf can solve both these practical issues.
IMHO, there is no need to remove or replace the current pngs. They will show you the content of the pdf before you download it.
For someone new to sphinx going through the simple setup is quite difficult and confusing to figure out how to use autodoc:
User visits
https://sphinx-tutorial.readthedocs.io/cheatsheet/
but no matter how they try, all they can see are rather blurry low resolution images of the cheat sheet.
I would make a non-image version.
The directive .. code-block::
is erroneously listed as .. codeblock::
in cheatsheet-back-full.png
.
I had to modify one line in 'pycon-sphinx-tutorial/src/crawler/main.py' to deal with an import exception:
'from utils import log, shouldignore'. To import the module 'main' so that Crawler Python API is displayed correctly one could either comment out the line or put it inside a try/except block:
try:
from utils import log, shouldignore
except ImportError:
pass
The command 'make html' now runs without WARNING and the page displays as intended, 'tho this will presumably affect the log and shouldignore flags elsewhere in the tutorial.
The installation part (http://sphinx-tutorial.readthedocs.org/start/) should be more "for the dummies" oriented:
I'm going though the Sphinx tutorial and everything is working great, except for the preformatted text section backgrounds. They turn out grey, but when I click on the Live Preview links, the example pages have #eeffcc background color. I'm using the sphinx_rtd_theme as recommended and configured it according to the instructions. How can I get the #eeffcc background color which seems to be standard?
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.