First markdown cell exported as a docstring in sphinx format #107

jupytext/jupytext.py

@@ -91,7 +91,13 @@ def writes(self, nb, **kwargs):
         lines.extend(metadata_and_cell_to_header(nb, self.format, self.ext))
 
         cell_exporters = []
+        looking_for_first_markdown_cell = self.format.format_name and self.format.format_name.startswith('sphinx')
+
         for cell in nb.cells:
+            if looking_for_first_markdown_cell and cell.cell_type == 'markdown':
+                cell.metadata['cell_marker'] = '"""'
+                looking_for_first_markdown_cell = False
+
             cell_exporters.append(self.format.cell_exporter_class(
                 cell, default_language, self.format.extension, comment_magics))
 

tests/notebooks/mirror/ipynb_to_sphinx/World population.py

@@ -16,14 +16,15 @@
 #     version: 3.6.6
 # ---
 
-###############################################################################
-# # A quick insight at world population
-#
-# ## Collecting population data
-#
-# In the below we retrieve population data from the
-# [World Bank](http://www.worldbank.org/)
-# using the [wbdata](https://github.com/OliverSherouse/wbdata) python package
+"""
+# A quick insight at world population
+
+## Collecting population data
+
+In the below we retrieve population data from the
+[World Bank](http://www.worldbank.org/)
+using the [wbdata](https://github.com/OliverSherouse/wbdata) python package
+"""
 
 import pandas as pd
 import wbdata as wb

tests/notebooks/mirror/ipynb_to_sphinx/convert_to_py_then_test_with_update83.py

@@ -23,7 +23,8 @@
 
 print('asdf')
 
-###############################################################################
-# Thanks for jupytext!
+"""
+Thanks for jupytext!
+"""
 
 

tests/notebooks/mirror/ipynb_to_sphinx/jupyter.py

@@ -16,10 +16,11 @@
 #     version: 3.6.4
 # ---
 
-###############################################################################
-# # Jupyter notebook
-#
-# This notebook is a simple jupyter notebook. It only has markdown and code cells. And it does not contain consecutive markdown cells. We start with an addition:
+"""
+# Jupyter notebook
+
+This notebook is a simple jupyter notebook. It only has markdown and code cells. And it does not contain consecutive markdown cells. We start with an addition:
+"""
 
 a = 1
 b = 2

tests/notebooks/mirror/ipynb_to_sphinx/sample_rise_notebook_66.py

@@ -16,8 +16,9 @@
 #     version: 3.6.6
 # ---
 
-###############################################################################
-# A markdown cell
+"""
+A markdown cell
+"""
 
 1+1
 

tests/test_read_simple_sphinx.py

@@ -6,10 +6,10 @@
 jupytext.header.INSERT_AND_CHECK_VERSION_NUMBER = False
 
 
-def test_read_simple_file(script="""# -*- coding: utf-8 -*-
-'''
+def test_read_simple_file(script='''# -*- coding: utf-8 -*-
+"""
 This is a markdown cell
-'''
+"""
 
 1 + 2 + 3 + 4
 5
@@ -22,9 +22,9 @@ def test_read_simple_file(script="""# -*- coding: utf-8 -*-
 # Another markdown cell
 
 def f(x):
-   '''Sample docstring'''
+   """Sample docstring"""
    return 4
-"""):
+'''):
     nb = jupytext.reads(script, ext='.py', format_name='sphinx')
     assert nb.cells[0].cell_type == 'code'
     assert nb.cells[0].source == '%matplotlib inline'
@@ -44,9 +44,9 @@ def f(x):
     assert nb.cells[4].source == 'Another markdown cell'
 
     assert nb.cells[5].cell_type == 'code'
-    assert nb.cells[5].source == """def f(x):
-   '''Sample docstring'''
-   return 4"""
+    assert nb.cells[5].source == '''def f(x):
+   """Sample docstring"""
+   return 4'''
     assert len(nb.cells) == 6
 
     script2 = jupytext.writes(nb, ext='.py', format_name='sphinx')
@@ -107,11 +107,12 @@ def test_read_more_complex_file(script="""'''This is a markdown cell'''
     assert len(nb.cells) == 9
 
 
-def test_read_empty_code_cell(script="""##################################
-# Markdown cell
+def test_read_empty_code_cell(script='''"""
+Markdown cell
+"""
 
 
-"""):
+'''):
     nb = jupytext.reads(script, ext='.py', format_name='sphinx')
 
     assert nb.cells[0].cell_type == 'code'