Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Jump to bottom

Autogenerated toctree showing internal links of files #276

Open
1 of 2 tasks
imujjwal96 opened this issue Jul 18, 2017 · 8 comments
Open
1 of 2 tasks

Autogenerated toctree showing internal links of files #276

imujjwal96 opened this issue Jul 18, 2017 · 8 comments

Comments

@imujjwal96
Copy link
Contributor

imujjwal96 commented Jul 18, 2017 •
edited
Loading

This is a

  • Bug report
  • Feature request

Current behaviour

Generating the docs for fossasia/pslab-desktop-apps, it was noticed that the toctree created in the autogenerated index.rst, alongwith the links to external files in the docpath, also shows internal links of the files unindented.

@jithinbp mentioned it here: fossasia/pslab-desktop#159 (comment)

The same thing was reproduced when i generated docs for imujjwal96/mydoc.

Generated docs: http://yaydoc.herokuapp.com/preview/[email protected]/affff33e-d640-405c-b262-56616d96016d_preview/

Screenshot

image

Detailed logs

Cloning Repository...

Repository Cloned Successfully!


export VERSION="development"
export MOCK_MODULES=""
export SUBPROJECT_DOCPATHS=""
export AUTOAPI_PYTHON="false"
export AUTOAPI_JAVA="false"
export DOCURL="yaydoc.fossasia.org"
export LOGO=""
export AUTOAPI_PYTHON_PATH="."
export AUTHOR="FOSSASIA"
export MARKDOWN_FLAVOUR="markdown_github"
export DOCPATH="docs"
export SUBPROJECT_URLS=""
export AUTOAPI_JAVA_PATH="."
export PROJECTNAME="Yaydoc"

Setting up documentation sources

Creating file ./conf.py.
Creating file ./index.rst.
Creating file ./Makefile.
Creating file ./make.bat.

Finished: An initial directory structure has been created.

You should now populate your master file ./index.rst and create other documentation
source files. Use the Makefile to build the docs, like so:
   make builder
where "builder" is one of the supported builders, e.g. html, latex or linkcheck.

Documentation setup successful!


--------------------------------------

.. include:: ../README.rst

.. toctree::
   :maxdepth: 1
   :caption: Contents

   parsers
   commitStyle

.. toctree::
   :maxdepth: 1
   :caption: Aaa

   aaa/about

.. toctree::
   :maxdepth: 1
   :caption: Installation

   installation/installation_heroku
   installation/installation_docker_gcloud
   installation/installation_docker
   installation/installation_cloud9
   installation/installation_kubernetes_gcloud
   installation/installation_docker_aws
   installation/installation_docker_bluemix
   installation/installation_windows_generic
   installation/installation_generic
   installation/eclipseSetup
   installation/installation_docker_digitalocean

.. toctree::
   :maxdepth: 1
   :caption: Skills

   skills/susi_questions
   skills/submitting_skills_to_git
   skills/susi_chat_api
   skills/susi_skill_development_tutorial

--------------------------------------

Auto generated index.rst

Starting Documentation Generation...

Running Sphinx v1.5.5
making output directory...
WARNING: while setting up extension conf.py: directive 'include' is already registered, it will be overridden
loading pickled environment... not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 19 source files that are out of date
updating environment: 19 added, 0 changed, 0 removed
reading sources... [  5%] aaa/about
reading sources... [ 10%] commitStyle
reading sources... [ 15%] index
reading sources... [ 21%] installation/eclipseSetup
reading sources... [ 26%] installation/installation_cloud9
reading sources... [ 31%] installation/installation_docker
reading sources... [ 36%] installation/installation_docker_aws
reading sources... [ 42%] installation/installation_docker_bluemix
reading sources... [ 47%] installation/installation_docker_digitalocean
reading sources... [ 52%] installation/installation_docker_gcloud
reading sources... [ 57%] installation/installation_generic
reading sources... [ 63%] installation/installation_heroku
reading sources... [ 68%] installation/installation_kubernetes_gcloud
reading sources... [ 73%] installation/installation_windows_generic
reading sources... [ 78%] parsers
reading sources... [ 84%] skills/submitting_skills_to_git
reading sources... [ 89%] skills/susi_chat_api
reading sources... [ 94%] skills/susi_questions
reading sources... [100%] skills/susi_skill_development_tutorial

/app/temp/[email protected]/affff33e-d640-405c-b262-56616d96016d/yaydoctemp/commitStyle.md:0: ERROR: Document may not end with a transition.
../README.rst:74: WARNING: Title underline too short.

Where can I download ready-built releases of Susi AI?
--------------------------------------------------
../README.rst:83: WARNING: Title underline too short.

How do I install Susi AI with Docker on Google Cloud?
----------------------------------
../README.rst:83: WARNING: Title underline too short.

How do I install Susi AI with Docker on Google Cloud?
----------------------------------
../README.rst:88: WARNING: Title underline too short.

How do I install Susi AI with Docker on AWS?
----------------------------------
../README.rst:88: WARNING: Title underline too short.

How do I install Susi AI with Docker on AWS?
----------------------------------
../README.rst:93: WARNING: Title underline too short.

How do I install Susi AI with Docker on Bluemix ?
----------------------------------
../README.rst:93: WARNING: Title underline too short.

How do I install Susi AI with Docker on Bluemix ?
----------------------------------
../README.rst:98: WARNING: Title underline too short.

How do I install Susi AI with Docker on Digital Ocean ?
----------------------------------
../README.rst:98: WARNING: Title underline too short.

How do I install Susi AI with Docker on Digital Ocean ?
----------------------------------
../README.rst:103: WARNING: Title underline too short.

How do I deploy Susi AI with Heroku?
---------------------------------
../README.rst:103: WARNING: Title underline too short.

How do I deploy Susi AI with Heroku?
---------------------------------
../README.rst:108: WARNING: Title underline too short.

How do I deploy Susi AI with cloud9?
---------------------------------
../README.rst:108: WARNING: Title underline too short.

How do I deploy Susi AI with cloud9?
---------------------------------
../README.rst:113: WARNING: Title underline too short.

How do I setup Susi AI on Eclipse?
-------------------------------
../README.rst:113: WARNING: Title underline too short.

How do I setup Susi AI on Eclipse?
-------------------------------
../README.rst:119: WARNING: Title underline too short.

How do I run Susi AI?
------------------
../README.rst:119: WARNING: Title underline too short.

How do I run Susi AI?
------------------
../README.rst:127: WARNING: Title underline too short.

How do I analyze data acquired by Susi AI
--------------------------------------
../README.rst:127: WARNING: Title underline too short.

How do I analyze data acquired by Susi AI
--------------------------------------
../README.rst:141: WARNING: Title underline too short.

How do I configure Susi AI?
------------------------
../README.rst:141: WARNING: Title underline too short.

How do I configure Susi AI?
------------------------
../README.rst:175: ERROR: Unexpected indentation.
../README.rst:178: WARNING: Title underline too short.

How do I develop Skills (AI Conversation Rules) for Susi AI?
---------------------------------------------------------
../README.rst:178: WARNING: Title underline too short.

How do I develop Skills (AI Conversation Rules) for Susi AI?
---------------------------------------------------------
../README.rst:184: WARNING: Title underline too short.

Why should I use Susi AI?
----------------------
../README.rst:184: WARNING: Title underline too short.

Why should I use Susi AI?
----------------------
../README.rst:189: WARNING: Title underline too short.

Where can I get the latest news about Susi AI?
-------------------------------------------
../README.rst:189: WARNING: Title underline too short.

Where can I get the latest news about Susi AI?
-------------------------------------------
../README.rst:0: WARNING: nonlocal image URI found: https://badges.gitter.im/fossasia/susi_server.svg
../README.rst:0: WARNING: nonlocal image URI found: https://travis-ci.org/fossasia/susi_server.svg?branch=development
../README.rst:0: WARNING: nonlocal image URI found: http://isitmaintained.com/badge/open/fossasia/susi_server.svg
../README.rst:0: WARNING: nonlocal image URI found: http://isitmaintained.com/badge/resolution/fossasia/susi_server.svg
../README.rst:0: WARNING: nonlocal image URI found: https://img.shields.io/twitter/url/http/shields.io.svg?style=social
../README.rst:0: WARNING: nonlocal image URI found: https://img.shields.io/twitter/follow/lklknt.svg?style=social&label=Follow&maxAge=2592000?style=flat-square
../README.rst:0: WARNING: nonlocal image URI found: https://www.herokucdn.com/deploy/button.svg
../README.rst:0: WARNING: nonlocal image URI found: https://cdn.scalingo.com/deploy/button.svg
../README.rst:0: WARNING: nonlocal image URI found: https://bluemix.net/deploy/button.png
../README.rst:0: WARNING: nonlocal image URI found: https://files.cloud.docker.com/images/deploy-to-dockercloud.svg
../README.rst:0: WARNING: nonlocal image URI found: https://badges.gitter.im/fossasia/susi_server.svg
../README.rst:0: WARNING: nonlocal image URI found: https://travis-ci.org/fossasia/susi_server.svg?branch=development
../README.rst:0: WARNING: nonlocal image URI found: http://isitmaintained.com/badge/open/fossasia/susi_server.svg
../README.rst:0: WARNING: nonlocal image URI found: http://isitmaintained.com/badge/resolution/fossasia/susi_server.svg
../README.rst:0: WARNING: nonlocal image URI found: https://img.shields.io/twitter/url/http/shields.io.svg?style=social
../README.rst:0: WARNING: nonlocal image URI found: https://img.shields.io/twitter/follow/lklknt.svg?style=social&label=Follow&maxAge=2592000?style=flat-square
../README.rst:0: WARNING: nonlocal image URI found: https://www.herokucdn.com/deploy/button.svg
../README.rst:0: WARNING: nonlocal image URI found: https://cdn.scalingo.com/deploy/button.svg
../README.rst:0: WARNING: nonlocal image URI found: https://bluemix.net/deploy/button.png
../README.rst:0: WARNING: nonlocal image URI found: https://files.cloud.docker.com/images/deploy-to-dockercloud.svg
/app/temp/[email protected]/affff33e-d640-405c-b262-56616d96016d/yaydoctemp/installation/installation_docker_digitalocean.md:0: WARNING: nonlocal image URI found: http://i.imgur.com/wXXvg7W.png
/app/temp/[email protected]/affff33e-d640-405c-b262-56616d96016d/yaydoctemp/installation/installation_docker_digitalocean.md:0: WARNING: nonlocal image URI found: http://i.imgur.com/egW1HsV.png
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [  5%] aaa/about
writing output... [ 10%] commitStyle
writing output... [ 15%] index
writing output... [ 21%] installation/eclipseSetup
writing output... [ 26%] installation/installation_cloud9
writing output... [ 31%] installation/installation_docker
writing output... [ 36%] installation/installation_docker_aws
writing output... [ 42%] installation/installation_docker_bluemix
writing output... [ 47%] installation/installation_docker_digitalocean
writing output... [ 52%] installation/installation_docker_gcloud
writing output... [ 57%] installation/installation_generic
writing output... [ 63%] installation/installation_heroku
writing output... [ 68%] installation/installation_kubernetes_gcloud
writing output... [ 73%] installation/installation_windows_generic
writing output... [ 78%] parsers
writing output... [ 84%] skills/submitting_skills_to_git
writing output... [ 89%] skills/susi_chat_api
writing output... [ 94%] skills/susi_questions
writing output... [100%] skills/susi_skill_development_tutorial

/app/temp/[email protected]/affff33e-d640-405c-b262-56616d96016d/yaydoctemp/index.rst:32: WARNING: toctree contains reference to document u'skills/susi_skill_development_tutorial' that doesn't have a title: no link will be generated
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 53 warnings.

Build finished. The HTML pages are in _build/html.
Documentation Generated Successfully!

Setting up documentation for Download and Preview

Documentation setup successful!
@imujjwal96
Copy link
Contributor Author

@pri22296 Can you have a look at this

@imujjwal96
Copy link
Contributor Author

Looking at the markdown files for mydoc, i notice that the main headers are not rendered, due to error in the original markdown. I think the absence of a # header is causing this.

Also, in pslab-desktop-apps, the markdowns start with mdheaders instead of # header. @jithinbp

@pri22296 Can you verify if these are the sources of errors?

@pri22296
Copy link
Member

I believe if the mdheaders like

---
layout: expt
title: AC and DC
date: 2017-05-28
description: Study the difference between AC and DC circuits
---

are replaced by

# AC and DC

The subheading will be nested properly.

@imujjwal96
Copy link
Contributor Author

imujjwal96 commented Jul 18, 2017 •
edited
Loading

Even github handle them as a table. What can we do with it? Should we do anything?

image

@imujjwal96
Copy link
Contributor Author

I don't see a mention of these headers anywhere. @pri22296 Did you find something?

@pri22296
Copy link
Member

Currently the markdown_flavour option is only used by pandoc, not recommonmark. As most of the markdown files are processed using recommonmark which uses a CommonMark Parser. I don't think mdheaders are part of the commonmark spec so we can't do anything about them now.

@imujjwal96
Copy link
Contributor Author

@jithinbp What do you say?

@jithinbp
Copy link

jithinbp commented Jul 18, 2017 •
edited
Loading

The syntax used seems to be specific to Jekyll.
The mdheaders are used to convey variables to the template files. And jekyll needs them to be right at the top.
Example

---
layout: expt
title: Lemon cell
date: 2017-05-21
description: experiments with a lemon cell
---

The entire markdown file can be viewed here https://raw.githubusercontent.com/fossasia/pslab-desktop-apps/development/docs/_apps/B_LEMON_CELL.md

The variables declared in the header section can include details such as author-name, title, description, layout to be used, custom variable etc . The title and description are specially formatted as shown
psl_lemon

The use of variables also provides flexibility in autogenerating TOCtrees from specific directories. For example, the title variable can be used as the link-text, and the description variable can be rendered as the onhover tooltip for that particular link

These variables are readable by the template files. For example, in some md files, I merely specify a variable called imagebase : This is read by the template, and it automatically renders the schematic, screenshot, and photograph with the same suffix as the imagebase variable ,and adds them to the generated static page.
I may have to redo the markdown files if we switch from Jekyll to yaydoc

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@jithinbp @imujjwal96 @pri22296