Skip to contentSkip to conversation

documentation: Add Pipenv support

PATCH In review Joshua Watt 4 participants 6 messages Nov 10, 2020 – Nov 12, 2020

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 documentation: Add Pipenv support

Adds a Pipfile so that Pipenv can be used to automatically install all the dependencies required to build the documentation

---
 documentation/.gitignore |  1 +
 documentation/Pipfile    | 14 ++++++++++++++
 documentation/README     |  7 +++++++
 3 files changed, 22 insertions(+)
 create mode 100644 documentation/Pipfile
documentation/.gitignore +1 -0
index 69fa449dd..21bb72530 100644
@@ -1 +1,2 @@
 _build/
+Pipfile.lock
documentation/Pipfile new file +14 -0
new file mode 100644
index 000000000..7ee1d2290
@@ -0,0 +1,14 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[dev-packages]
+
+[packages]
+sphinx = "*"
+sphinx-rtd-theme = "*"
+pyyaml = "*"
+
+[requires]
+python_version = "3"
documentation/README +7 -0
index 534ae66f8..28d5c4be8 100644
@@ -127,6 +127,13 @@ The resulting HTML index page will be _build/html/index.html, and you
 can browse your own copy of the locally generated documentation with
 your browser.
 
+Alternatively, you can use Pipenv to automatically install all required
+dependencies in a virtual environment:
+
+ $ cd documentation
+ $ pipenv install
+ $ pipenv run make html
+
 Sphinx theme and CSS customization
 ==================================
 
Signature · 1 line
2.29.2
#1 lore raw

Hi Joshua,

I would suggest adding [sphinx-serve](https://pypi.org/project/sphinx-serve/) as a dev-package to serve the docs during local development/tests.

I was able to serve the Sphinx-RTD on my machine simply by executing sphinx-serve in the documentations/ folder. Maybe mention it in the README too?.

I think Pipenv might be required since I was digging into the Algolia Search Indexing and there you can use their document scraper with Pipenv as well. (see https://docsearch.algolia.com/docs/run-your-own/)

Might be worth the effort, since Nico did mention plans to use an indexing search for the new docs.

Would love your thoughts on this.

Regards,

Shan

#2 lore raw
Quoted 5 lines · On 11/11/20 3:30 PM, [email protected] wrote:

Hi Joshua,

I would suggest adding sphinx-serve <https://pypi.org/project/sphinx-serve/> as a dev-package to serve the docs during local development/tests.

I'd be fine with that. We can see if anyone else objects, or we can also merge as is and add that as a separate patch.

Quoted 15 lines

I was able to serve the Sphinx-RTD on my machine simply by executing |sphinx-serve| in the |documentations/| folder. Maybe mention it in the README too?.

I think Pipenv might be required since I was digging into the Algolia Search Indexing and there you can use their document scraper with Pipenv as well. (see https://docsearch.algolia.com/docs/run-your-own/)

Might be worth the effort, since Nico did mention plans to use an indexing search for the new docs.

Would love your thoughts on this.

Regards,

Shan

#3 lore raw

hey Shan,

can you please avoid top posting and using html for emails to the list? this makes it harder for us to follow.

Quoted 9 lines · Joshua Watt

On 11/11/20 3:30 PM, [email protected] wrote:

Hi Joshua,

I would suggest adding sphinx-serve as a dev-package to serve the docs during local development/tests.

I'd be fine with that. We can see if anyone else objects, or we can also merge as is and add that as a separate patch.

I never used it, but why not. I just tried it, and it worked. But it's definitely another patch on its own.

Quoted 19 lines

I was able to serve the Sphinx-RTD on my machine simply by executing sphinx-serve in the documentations/ folder. Maybe mention it in the README too?.

I think Pipenv might be required since I was digging into the Algolia Search Indexing and there you can use their document scraper with Pipenv as well. (see https://docsearch.algolia.com/docs/run-your-own/)

Might be worth the effort, since Nico did mention plans to use an indexing search for the new docs.

Would love your thoughts on this.

Regards,

Shan

#4 lore raw
Quoted 10 lines · Nicolas Dechesne

hey Shan,

can you please avoid top posting and using html for emails to the list? this makes it harder for us to follow.

Quoted 4 lines · Joshua Watt

On 11/11/20 3:30 PM, [email protected] wrote:

Quoted 9 lines
Quoted 5 lines

Hi Joshua,

I would suggest adding sphinx-serve as a dev-package to serve the docs during local development/tests.

I'd be fine with that. We can see if anyone else objects, or we can also merge as is and add that as a separate patch.

I never used it, but why not. I just tried it, and it worked. But it's definitely another patch on its own.

What's the benefit over using python3 -m http.server or python -m SimpleHTTPServer? (since those are part of the python standard library AFAICT, no need to install new packages).

Thanks,
Quentin

#5 lore raw
Quoted 18 lines · Quentin Schulz
Quoted 16 lines · Nicolas Dechesne

hey Shan,

can you please avoid top posting and using html for emails to the list? this makes it harder for us to follow.

Quoted 9 lines · Joshua Watt

On 11/11/20 3:30 PM, [email protected] wrote:

Hi Joshua,

I would suggest adding sphinx-serve as a dev-package to serve the docs during local development/tests.

I'd be fine with that. We can see if anyone else objects, or we can also merge as is and add that as a separate patch.

Quoted 7 lines
Quoted 3 lines

I never used it, but why not. I just tried it, and it worked. But it's definitely another patch on its own.

What's the benefit over using python3 -m http.server or python -m SimpleHTTPServer? (since those are part of the python standard library AFAICT, no need to install new packages).

hmm. right, I thought it might do more.. like updating/building in the background.. but looking at:
https://github.com/tlatsas/sphinx-serve/blob/master/sphinx_serve/sphinx_serve.py

it really doesn't do anything, only construct the --directory..

I don't think we should carry the extra dependency then.

Quoted 3 lines

Thanks,
Quentin