1. sphinx Makefile To create the Makefile, I used sphinx-quickstart inside of sage -sh which ask many questions including this one:
""" A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly. > Create Makefile? (y/n) [y]: """ 2. sphinx conf.py I then compared the generated files conf.py, Makefile, index.rst with the one of Sage and the ones of https://github.com/sagemath/cysignals and I may have done some hand made modifications to allow macros like `\ZZ` or :arxiv:`...` to be recognized. For example, see the line # -- Options copied from Sagemath conf.py file ------------------------------- at https://github.com/seblabbe/slabbe/blob/master/docs/source/conf.py#L286 3. __init__.py For sphinx to work, I also needed to import sage command line in the __init__.py file: https://github.com/seblabbe/slabbe/blob/master/slabbe/__init__.py#L6 4. Building the doc: In my makefile at https://github.com/seblabbe/slabbe/blob/master/makefile the command I currently use to build the docs are: doc: cd docs && sage -sh -c "make html" doc-pdf: cd docs && sage -sh -c "make latexpdf" 5. autodoc I do not remember why, but I was not able to use the sage-sphinx-autodoc extensions which creates automatically the .rst files in the docs/ folder. I managed to use the sphix-autodoc extension, but it not fun because the autogenerated .rst files have bad title names (the module names). The sage-sphinx-autodoc extension is better, because it reuses the first line of the toplevel documentation. But I was unable to use it for my optional package. Therefore, for now I have handwritten every .rst files inside my docs/ folder. Tell me if you find anything which improves my current work flow... Cheers, Sébastien -- You received this message because you are subscribed to the Google Groups "sage-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to sage-devel+unsubscr...@googlegroups.com. To post to this group, send email to sage-devel@googlegroups.com. Visit this group at https://groups.google.com/group/sage-devel. For more options, visit https://groups.google.com/d/optout.
