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.

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

Improve automatic building of docs #280

Closed
damiansteiger opened this issue Oct 26, 2018 · 5 comments · Fixed by #339
Closed

Improve automatic building of docs #280

damiansteiger opened this issue Oct 26, 2018 · 5 comments · Fixed by #339

Comments

@damiansteiger
Copy link
Contributor

It would be great to fully automate the building of ProjectQ's docs using sphinx. Two tasks are currently done manually:

@Abby3017
Copy link

I like to take up this task to automate the building of docs. Is it still available or the requirements are still same ??

@Takishima
Copy link
Collaborator

The task is still available and as far as I know, the requirements are the same. If you have suggestions on how to improve any aspect of it, feel free to discuss them here.

@Abby3017
Copy link

Thanks for letting me know. I will work on it and if some issue or suggestion is there, I will let you know.

@Abby3017
Copy link

Suggestions:

  1. This line is causing issue conf.py as info is coming empty and make clean html is failing. I put a condition of if not info['module'] to check if it is present then run the eval. Are you getting same error on running make command.
  2. Can I create a dev_requirement.txt that have sphinx sphinx_rtd_theme as there requirements as it will be easy for someone else to install package in one go and make docs

Questions

  1. Can you clarify more about automate building of docs. Do you want something on this line.
  2. Currently both link point to same url. On make command I was able to build it. I didn't have to do anything manually. Can you check that again or I missed something.

It would be great if you can answer these queries.

@Takishima
Copy link
Collaborator

Takishima commented May 28, 2019

Here are my answers to your suggestions/questions.

Suggestions:

  1. According to the Sphinx documentation [1], if the domain is 'py', the info dictionary is guaranteed to contain both 'module' and 'fullname' keys, so I do not think that your check is needed. Maybe you could try making sure sphinx is up-to-date?
  2. I do not think this is necessary, people who want to build the ProjectQ documentation on their own should be able to manage that. Most users will never have to bother with these requirements anyway.

Questions:

  1. ProjectQ is currently using ReadTheDocs [2] to generate and host the documentation of the project. There is no plan at the moment to change that.
  2. As Improve automatic building of docs #280 mentions, the two steps that are currently done manually is the generation of the .. autosummary:: part of the *.rstfiles, as well as the Submodules part of the decomposition.rst file.

In essence, what would be needed is to figure out how to automatically generate the two aspects mentioned in #280 during the build process of ReadTheDocs [2].

[1] http://www.sphinx-doc.org/en/master/usage/extensions/linkcode.html
[2] https://readthedocs.org

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants