Improving support for Markdown syntaxis in documentation entries.

mathics/builtin/numeric.py

@@ -625,8 +625,9 @@ class RealValuedNumberQ(Builtin):
     # No docstring since this is internal and it will mess up documentation.
     # FIXME: Perhaps in future we will have a more explicite way to indicate not
     # to add something to the docs.
+    no_doc = True
     context = "Internal`"
-
+    summary_text = "test whether an expression is a real number"
     rules = {
         "Internal`RealValuedNumberQ[x_Real]": "True",
         "Internal`RealValuedNumberQ[x_Integer]": "True",
@@ -639,6 +640,7 @@ class RealValuedNumericQ(Builtin):
     # No docstring since this is internal and it will mess up documentation.
     # FIXME: Perhaps in future we will have a more explicite way to indicate not
     # to add something to the docs.
+    no_doc = True
     context = "Internal`"
 
     rules = {

mathics/doc/__init__.py

@@ -1,8 +1,29 @@
 # -*- coding: utf-8 -*-
 """
-Module for handling Mathics-style documentation.
+A module and library that assists in organizing document data
+located in static files and docstrings from
+Mathics3 Builtin Modules. Builtin Modules are written in Python and
+reside either in the Mathics3 core (mathics.builtin) or are packaged outside,
+in Mathics3 Modules e.g. pymathics.natlang.
 
-Right now this covers common LaTeX/PDF and routines common to
-Mathics Django. When this code is moved out, perhaps it will
-include the Mathics Django-specific piece.
+This data is stored in a way that facilitates:
+* organizing information to produce a LaTeX file
+* running documentation tests
+* producing HTML-based documentation
+
+The command-line utility ``docpipeline.py``, loads the data from
+Python modules and static files, accesses the functions here.
+
+Mathics Django also uses this library for its HTML-based documentation.
+
+The Mathics3 builtin function ``Information[]`` also uses to provide the
+information it reports.
+As with reading in data, final assembly to a LaTeX file or running
+documentation tests is done elsewhere.
+
+FIXME: This code should be replaced by Sphinx and autodoc.
+Things are such a mess, that it is too difficult to contemplate this right now. 
+Also there higher-priority flaws that are more more pressing.
+In the shorter, we might we move code for extracting printing to a
+separate package.
 """