[docs][PATCH] documentation: Add Pipenv support

[docs][PATCH] documentation: Add Pipenv support

[Joshua Watt]

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

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
---
 documentation/.gitignore |  1 +
 documentation/Pipfile    | 14 ++++++++++++++
 documentation/README     |  7 +++++++
 3 files changed, 22 insertions(+)
 create mode 100644 documentation/Pipfile

diff --git a/documentation/.gitignore b/documentation/.gitignore
index 69fa449dd..21bb72530 100644
--- a/documentation/.gitignore
+++ b/documentation/.gitignore
@@ -1 +1,2 @@
 _build/
+Pipfile.lock
diff --git a/documentation/Pipfile b/documentation/Pipfile
new file mode 100644
index 000000000..7ee1d2290
--- /dev/null
+++ b/documentation/Pipfile
@@ -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"
diff --git a/documentation/README b/documentation/README
index 534ae66f8..28d5c4be8 100644
--- a/documentation/README
+++ b/documentation/README
@@ -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
 ==================================
 
-- 
2.29.2

Re: [PATCH] documentation: Add Pipenv support

[shantanoo.desai]

[-- Attachment #1: Type: text/plain, Size: 692 bytes --]

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



[-- Attachment #2: Type: text/html, Size: 872 bytes --]

Re: [docs] [PATCH] documentation: Add Pipenv support

[Joshua Watt]

[-- Attachment #1: Type: text/plain, Size: 934 bytes --]


On 11/11/20 3:30 PM, shantanoo.desai@gmail.com 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.

> 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
>
>
> 
>

[-- Attachment #2: Type: text/html, Size: 1973 bytes --]

Re: [docs] [PATCH] documentation: Add Pipenv support

[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.

On Wed, Nov 11, 2020 at 11:05 PM Joshua Watt <JPEWhacker@gmail.com> wrote:
>
>
> On 11/11/20 3:30 PM, shantanoo.desai@gmail.com 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.

>
> 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
>
>
>
>
>
> 
>

Re: [docs] [PATCH] documentation: Add Pipenv support

[Quentin Schulz]

On Thu, Nov 12, 2020 at 08:29:34AM +0100, Nicolas Dechesne wrote:
> hey Shan,
> 
> can you please avoid top posting and using html for emails to the
> list? this makes it harder for us to follow.
> 
> On Wed, Nov 11, 2020 at 11:05 PM Joshua Watt <JPEWhacker@gmail.com> wrote:
> >
> >
> > On 11/11/20 3:30 PM, shantanoo.desai@gmail.com 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.
> 

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

Re: [docs] [PATCH] documentation: Add Pipenv support

[Nicolas Dechesne]

On Thu, Nov 12, 2020 at 10:42 AM Quentin Schulz
<quentin.schulz@streamunlimited.com> wrote:
>
> On Thu, Nov 12, 2020 at 08:29:34AM +0100, Nicolas Dechesne wrote:
> > hey Shan,
> >
> > can you please avoid top posting and using html for emails to the
> > list? this makes it harder for us to follow.
> >
> > On Wed, Nov 11, 2020 at 11:05 PM Joshua Watt <JPEWhacker@gmail.com> wrote:
> > >
> > >
> > > On 11/11/20 3:30 PM, shantanoo.desai@gmail.com 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.
> >
>
> 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.

>
> Thanks,
> Quentin