Skip to main content

Sphinx extension to use with Recommonmark to fix links to rst from md, links to md from rst, and links to embedded files and dirs.

Project description

Sphinx Markdown Extension

This extension fixes or improves how Sphinx handles links related to Markdown when it generates the HTML site. It assumes you are using the recommonmark extension. It's a good idea to use sphinx_markdown_tables as well.

Contents

What it does

  1. Markdown files: Converts references to Markdown files that include anchors.

    [configuration options](autotest.md#configuration-options)
    
  2. reST files: Fixes explicit links to Markdown files.

    `Google Cloud Engine <gce.md>`__
    
  3. Markdown files: Fixes references to reST files.

    [Application examples](examples/readme.rst)
    
  4. Markdown files: Fixes links to files and directories within the GitHub repo.

    [Makefile](/Makefile)
    [deploy/kustomize](/deploy/kustomize)
    

    Links to files can be fixed one of two ways, which can be set in the conf.py.

    baseBranch = "devel"
    useGitHubURL = True
    commitSHA = getenv('GITHUB_SHA')
    githubBaseURL = "https://github.com/intelkevinputnam/pmem-csi/"
    

    If useGitHubURL is set to True, it will try to create links based on your githubBaseURL and the SHA for the commit to the GitHub repo determined by the GitHub workflow on merge). If there is no SHA available, it will use the value of baseBranch.

    If useGitHubURL is set to False, it will copy the files to the HTML output directory and provide links to that location.

    NOTE: Links to files and directories should use absolute paths relative to the repo (see Makefile and deploy/kustomize above). This will work both for the Sphinx build and when viewing in the GitHub repo.

    Links to directories are always converted to links to the GitHub repository.

How to use it

  1. Install the sphinx_md extension:

    pip3 install sphinx_md
    
  2. Add sphinx_md to the extensions in your conf.py:

    extensions = ['sphinx_md', ...]
    
  3. If you want to use GitHub commit links, add the entire code snippet to your conf.py:

    from os import getenv
    
    sphinx_md_useGitHubURL = True
    baseBranch = "devel"
    commitSHA = getenv('GITHUB_SHA')
    githubBaseURL = 'https://github.com/' + (getenv('GITHUB_REPOSITORY') or '<your_group/your_project>') + '/'
    githubFileURL = githubBaseURL + "blob/"
    githubDirURL = githubBaseURL + "tree/"
    if commitSHA:
        githubFileURL = githubFileURL + commitSHA + "/"
        githubDirURL = githubDirURL + commitSHA + "/"
    else:
        githubFileURL = githubFileURL + baseBranch + "/"
        githubDirURL = githubDirURL + baseBranch + "/"
    sphinx_md_githubFileURL = githubFileURL
    sphinx_md_githubDirURL = githubDirURL
    

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-md-0.0.3.tar.gz (6.6 kB view hashes)

Uploaded Source

Built Distribution

sphinx_md-0.0.3-py3-none-any.whl (7.4 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page