Skip to content

WIP [ENH, DOC] Documentation PDF - automatic generation #797

New issue

Have a question about this project? # for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “#”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? # to your account

Open
wants to merge 40 commits into
base: main
Choose a base branch
from

Conversation

juangpc
Copy link
Collaborator

@juangpc juangpc commented May 26, 2021

Hi,
The pr will create a pdf from the markdown files in the doc/gh-pages folder. Eventually, it could turn into an independent repository with a gh action that we could download from the ci, and trigger whenever a pr was accepted into master.

Coded in Python, and based in a Latex template, it creates two python modules (so far). One a basic mne-cpp core module with basic functions we might need during development, and another module related to the actual pdf generation.

To do:

  • - Analyze markdown files in doc/gh-pages folder.
  • - Generate a graph of connections and dependencies between md files: a web page.
  • - Generate a list of md files to not include in the pdf. (i.e. a Download page) This shouldn't rely in just the docs.
  • - Create an initial Latex file.
  • - Finish python parser (see below)
  • - Validate and test all the parsing routines created.
  • - Generate a single shell or python command that takes care of everything.
  • - Generate a CI action that calls the script and saves the corresponding pdf as an asset that we can then link in the actual web. We should do that through a markdown link itself (this page should probably not be included in the pdf).

Python parser code:

  • - correctly parse ordered / unordered combined lists.
  • - parse inbound links vs outbound links
  • - parse inline code
  • - parse multiple terms description/definition

Yes, the pr needs still some work.

@codecov-commenter
Copy link

codecov-commenter commented May 26, 2021

Codecov Report

Merging #797 (bcd13bd) into main (5f0f608) will not change coverage.
The diff coverage is n/a.

❗ Current head bcd13bd differs from pull request most recent head 4b3f914. Consider uploading reports for the commit 4b3f914 to get more accurate results
Impacted file tree graph

@@           Coverage Diff           @@
##             main     #797   +/-   ##
=======================================
  Coverage   29.52%   29.52%           
=======================================
  Files         450      450           
  Lines       39296    39296           
=======================================
  Hits        11603    11603           
  Misses      27693    27693           
Impacted Files Coverage Δ
libraries/utils/generics/applicationlogger.cpp 62.50% <0.00%> (-2.21%) ⬇️
...aries/disp3D/helpers/geometryinfo/geometryinfo.cpp 96.62% <0.00%> (-1.13%) ⬇️
libraries/mne/c/mne_surface_or_volume.cpp 48.71% <0.00%> (+0.05%) ⬆️
...pplications/mne_anonymize/settingscontrollercl.cpp 70.00% <0.00%> (+0.12%) ⬆️

@juangpc juangpc changed the title [WIP, ENH, DOC] Documentation PDF - automatic generation WIP [ENH, DOC] Documentation PDF - automatic generation Aug 17, 2021
# for free to join this conversation on GitHub. Already have an account? # to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants