Conversation
Codecov Report
@@ Coverage Diff @@
## master #9 +/- ##
=======================================
Coverage 48.89% 48.89%
=======================================
Files 8 8
Lines 4947 4947
=======================================
Hits 2419 2419
Misses 2528 2528
Continue to review full report at Codecov.
|
✌️ |
|
The doc is now published to https://galgebra.readthedocs.io/en/latest/index.html using this branch. @arsenovic @hugohadfield
|
| # Catch-all target: route all unknown targets to Sphinx using the new | ||
| # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). | ||
| %: Makefile | ||
| notedown galgebra.md > galgebra_guide.ipynb |
There was a problem hiding this comment.
I convert the .tex to a .md, fix it manually(a lot of work), and convert the .md to .ipynb using notedown and then use nbsphinx to convert the .ipynb to build the sphinx which is based on .rst.
My major concern for this method is that we have to maintain .md and generate .ipynb manually and commit it to git (readthedocs doesn't run this makefile). And it deviate from the original tex due to some MathJax limitations(especially of equation referencing).
You may wonder, why go through all these trouble? Because none of the direct method works:
- The original doc in tex form was written in a not so rigorous way, most of the equations are not surrounded in
$or$$, so pandoc didn't convert it properly to a .rst with math block. - .md, even with the help of recommonmark, is not properly handled by sphinx, especially the formulas, but after notedown and nbsphinx, it's much easier to fix
There was a problem hiding this comment.
This sounds super annoying, the docs look amazing though
There was a problem hiding this comment.
Yeah, that's why I gave myself some time to step back and see if there's a better way. So far it's still the best working way.
| @@ -0,0 +1,14 @@ | |||
| /* https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html */ | |||
| /* override table width restrictions */ | |||
There was a problem hiding this comment.
This is to fix the table. Without this, the long sentences in tables will overflow with horizontal scroll instead of wrap properly.
| {{ fullname }} | ||
| {{ underline }} | ||
|
|
||
| .. automodule:: {{fullname}} |
There was a problem hiding this comment.
This is to customize autosummary to render modules, or it will be in a bad shape for submodules.
doc/conf.py
Outdated
| # The short X.Y version | ||
| version = '' | ||
| # The full version, including alpha/beta/rc tags | ||
| release = '0.4.1.1' |
There was a problem hiding this comment.
Should use a constant from setup.py or somewhere common. I see it's also redundant in clifford.
There was a problem hiding this comment.
Yeah this is annoying for both libraries, maybe we can come up with a nice solution, probably not a big problem unless we start doing a lot of releases :)
There was a problem hiding this comment.
Yeah, it's not a big deal. We can just keep in mind to update both of them for every release for the time being.
There was a problem hiding this comment.
| import galgebra | ||
| import nbsphinx | ||
| # nbsphinx_execute = 'always' | ||
| nbsphinx_execute = 'never' |
There was a problem hiding this comment.
I need to disable the execution of notebooks because the python code in the original tex still requires a lot of fix.
doc/conf.py
Outdated
| "special-members", | ||
| "undoc-members", | ||
| "private-members", | ||
| "show-inheritance", |
There was a problem hiding this comment.
Currently I expose everything in the API doc to make spotting missing docs more easily.
doc/galgebra.md
Outdated
| @@ -0,0 +1,2009 @@ | |||
| This document describes the implementation, installation and use of a geometric algebra module written in python that utilizes the *sympy* symbolic algebra library. The python module ga has been developed for coordinate free calculations using the operations (geometric, outer, and inner products etc.) of geometric algebra. The operations can be defined using a completely arbitrary metric defined by the inner products of a set of arbitrary vectors or the metric can be restricted to enforce orthogonality and signature constraints on the set of vectors. Additionally, a metric that is a function of a coordinate set can be defined so that a geometric algebra over a manifold can be implemented. Geometric algebras over submanifolds of the base manifold are also supported as well as linear multivector differential operators and linear transformations. In addition the module includes the geometric, outer (curl) and inner (div) derivatives. The module requires the *sympy* module and the numpy module for numerical linear algebra calculations. For LaTeX output a LaTeX distribution and pdf viewer must be installed. If the user is interested in using geometric algebra for strictly numerical purposes I would recommend using the *glucat* C++ templates which have a python wrapper for python users (<http://glucat.sourceforge.net/>). | |||
There was a problem hiding this comment.
I removed the photos because they are not properly sized.
doc/galgebra.md
Outdated
| |:-|:-| | ||
| | linux | Comes with all versions of linux | | ||
| | windows | To install python on windows go to https://www.python.org/downloads/windows/ and install version appropriate for you version of windows. If you wish a more complete/advanced installation go to https://code.google.com/p/pythonxy/. | | ||
| | mac | Basic version comes with OSX. For better in-stallation go to http://docs.python-guide.org/en/ latest/starting/install/osx/. | |
There was a problem hiding this comment.
Pandoc is not good at converting tables and especially the multiline ones. All tables are fixed manually.
|
|
||
| <script type="text/x-mathjax-config"> | ||
| MathJax.Hub.Config({TeX: { equationNumbers: { autoNumber: "AMS" } }}); | ||
| </script> |
There was a problem hiding this comment.
I need to enable equation auto numbering for the references to work. This script will not be executed if I feed this .md directly to sphinx.
| MathJax.Hub.Config({TeX: { equationNumbers: { autoNumber: "AMS" } }}); | ||
| </script> | ||
|
|
||
| $$\newcommand{\bm}[1]{\boldsymbol{#1}} |
There was a problem hiding this comment.
The original tex used a lot of custom commands. I can't just expand them, because they make the tex source more simple and expressive. But in order to make all these custom commands to work, please note that:
- it won't work if fed to sphinix directly.
- if it's converted to ipynb, it won't work in a Jupyter Notebooks for the last parts of the document, because python codes separated the markdown so the environment is not passed on, but it works after converted through nbsphinx, because underlying they are in the same .rst
| dirac_eq.Fmt(3,r'%\text{Dirac Equation\;\;}\nabla \bm{\psi}'+\ | ||
| r' I \sigma_{z}-e\bm{A}\bm{\psi}-m\bm{\psi}\gamma_{t} = 0') | ||
| xpdf(paper='landscape',prog=True) | ||
| # FIXME terms of \psi^{ty} are not grouped together |
There was a problem hiding this comment.
All codes in doc/python are somehow not working in a non-trivial-to-fix way, but most of the prints are correct. All incorrect places are compared with my eyes and marked with FIXME. Still working on all the fixes.
doc/readthedocs-pip-requirements.txt
Outdated
| sphinx_rtd_theme | ||
| recommonmark | ||
| sphinx-markdown-tables | ||
| notedown No newline at end of file |
There was a problem hiding this comment.
I need the last three more dependencies than clifford.
| return result | ||
|
|
||
|
|
||
| def isstr(s): |
There was a problem hiding this comment.
In order to make string type test work under both python 2 and 3, I need this small util if I don't want to introduce six.
There was a problem hiding this comment.
Yeah the Python 2 to 3 string conversion is an absolute nightmare, if we get python3 support working well enough we can probably just ditch python2 support if it turns out to be an annoying problem
There was a problem hiding this comment.
So far the Python 2 support is not a big problem per se, with the help of CI and tools/libraries we can maintain good support for 2.7 & 3. Also I hope the releases from pygae won't make users having to choose between 2.7 and 3, especially we are at such an early stage of divergence.
Here's just some notes about trying to keep the dependencies minimal, so I prefered an utility function instead of introducing a dependency ( even it's a quite mature and ubiquitous one ).
| $\\DeclareMathOperator{\Tr}{Tr} | ||
| \\DeclareMathOperator{\Adj}{Adj} | ||
| """ | ||
| $\\DeclareMathOperator{\\Tr}{Tr} |
There was a problem hiding this comment.
I was wrong to add the r prefix(broke xpdf printing), I just need to fix the \T and \A without double backslashes.
| print_replace_new = None | ||
|
|
||
| SYS_CMD = {'linux2': {'rm': 'rm', 'evince': 'evince', 'null': ' > /dev/null', '&': '&'}, | ||
| 'linux': {'rm': 'rm', 'evince': 'evince', 'null': ' > /dev/null', '&': '&'}, |
There was a problem hiding this comment.
Without this line, the pdflatex can't be called under Linux.
| def com(A, B): | ||
| return ga.Ga.com(A, B) | ||
| raise ImportError( | ||
| """mv.com is removed, please use ga.Ga.com(A, B) instead.""") |
|
There're some strange difference between local build and readthedocs build: Local:
readthedocs:
which I have no clue. The .md and .ipynb are fine. |
| print('\\bm{a|(b^c^d)} =', a | (b ^ c ^ d)) | ||
| # FIXME this should print 0, got blank | ||
| print('\\bm{a|(b^c)+c|(a^b)+b|(c^a)} =', | ||
| (a | (b ^ c)) + (c | (a ^ b)) + (b | (c ^ a))) |
There was a problem hiding this comment.
Finally found the reason:
When added together, (a | (b ^ c)) + (c | (a ^ b)) + (b | (c ^ a))) is initially (a.b)c−(b.c)a−((a.b)c−(b.c)a), so it missed the first branch in GaLatexPrinter._print_Mv:
def _print_Mv(self, expr):
if expr.obj == S(0): # which equals False at this stage
return('0 \n')
else:
return expr.Mv_latex_str()But in Mv.Mv_latex_str(), some code modified expr.obj:
self.obj = expand(self.obj)
self.characterise_Mv()
self.obj = metric.Simp.apply(self.obj)After the lines above the self.obj now equals S(0).
So a simple yet hacky fix is to add the following after the code above:
if self.obj == S(0):
return ' 0 'But the real fix is to move the simplification-related logic out of the printer method.
The reason was found because I observed:
which indicated side effect in printing which is caused by:
which is caused by:
There was a problem hiding this comment.
which indicated side effect in printing
Hey look, you saw gh-141 coming over a year ago :)
There was a problem hiding this comment.
Ah......and finally you nailed it. I must have buried something else like this...
utensil
force-pushed
the
nbsphinx
branch
2 times, most recently
from
d9357a5 to
d8ca654
Compare
|
good job with all your work on this. my only comment is that you might consider adding a short 'crash course' or a 'quick intro' eventually. most people have short attention. |
|
dont forget to add link to the docs in the readme. |
|
Comments from codacy-bot for markdown files are super annoying, disabled them on Codacy:
|
|
@arsenovic @hugohadfield @waldyrious Now most of tasks are completed for a first iteration(see the main thread at the top, I kept updating the task, 16 of them has been completed), I propose to merge this PR as is and leave the following tasks to later PRs:
Comments welcome 😄 |
You're right, that is OK, and I did miss it due to the badges. Perhaps adding the sentence below the badges would make it more visible:
...but to be honest, now that you pointed out that the text was there, I can't unsee it anymore, and the current version actually looks good (especially in readthedocs, which adds more padding around the paragraph. So maybe it's not worth bikeshedding over that detail :) |
I think it's a good call to make improvements in further PRs. As a mostly curious layman with negligible mathematical background, I'll be happy to contribute in the development of approachable introductory material :) |
|
yes i think what you have is good. can be improved upon as time allows. |
|
Looks really good :) |
|
The failing doc build is simply because I pointed to branch nbsphinx on readthedocs.io, will rectify in a sec. EDIT: fixed. |
5 participants
My method is to automate when possible but do it manually when not.
pandoc -f latex -t markdown_github galgebra.tex -o galgebra.mdUpdated TODOs ( Feb 2019) :
doc/Tasks left for later PRs: